Recibos

O atual capítulo tem como objetivo descrever as rotas da API responsáveis pela gestão de recibos

Criação de recibos

Cada recibo é constituído por:

1. Um cabeçalho

2. Uma ou mais linhas

O recibo não possui um estado "em preparação".

Um recibo pode ser (3.) anulado.

1. Criação do cabeçalho do recibo

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

post

Body

application/json

Responses

200

OK

application/json

post

/commercial_sales_receipts

HTTPcURLJavaScriptPython

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

{
  "data": {
    "type": "commercial_sales_receipts",
    "attributes": {
      "id": 1,
      "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
    },
    "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"
        }
      },
      "customer": {
        "data": {
          "resource": "customers"
        }
      },
      "currency": {
        "data": {
          "resource": "currencies"
        }
      },
      "user": {
        "data": {
          "resource": "current_company_users"
        }
      },
      "lines": {
        "data": {
          "table": "receipt_lines",
          "resource": "commercial_sales_receipt_lines"
        }
      }
    }
  }
}

200

OK

{
  "data": {
    "type": "commercial_sales_receipts",
    "id": null,
    "attributes": {
      "id": 1,
      "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
    },
    "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"
        }
      },
      "customer": {
        "data": {
          "resource": "customers"
        }
      },
      "currency": {
        "data": {
          "resource": "currencies"
        }
      },
      "user": {
        "data": {
          "resource": "current_company_users"
        }
      },
      "lines": {
        "data": {
          "table": "receipt_lines",
          "resource": "commercial_sales_receipt_lines"
        }
      }
    }
  }
}

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>/commercial_sales_receipts'

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

{ 
  "data": {
    "type": "commercial_sales_receipts",                              // [OBRIGATÓRIO]
    "attributes": {
      "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.
    },
    "relationships": {                                                // [OPCIONAL] Recursos associados ao recibo. Caso nenhum seja indicado, este bloco "relationships" deve ser omitido
      "commercial_document_series": {                                 // [OPCIONAL] 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
        "data": {
          "type": "commercial_document_series",                       // [OBRIGATÓRIO]
          "id": "<id da série de recibos associada>"                  // [OBRIGATÓRIO] Vd. NOTA 1
        }
      },
      "bank_accounts": {                                              // [OPCIONAL] 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.
        "data": {
          "type": "bank_accounts",                                    // [OBRIGATÓRIO]
          "id": "<id da conta bancária>"                              // [OBRIGATÓRIO] Vd. NOTA 2
        }
      },
      "cash_accounts": {                                              // [OPCIONAL] 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.
        "data": {
          "type": "cash_accounts",                                    // [OBRIGATÓRIO]
          "id": "<id da conta de caixa associada>"                    // [OBRIGATÓRIO] Vd. NOTA 3// Este id pode ser obtido por um GET /cash_accounts?filter[name]=<nome da conta de caixa>
        }
      }
    }
  }
}

Após criar o cabeçalho, a resposta TEM QUE ser consultada para obtenção do identificador interno ("id") do recibo criado. Este identificador será necessário para a criação de todas as linhas.

• 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]=

2. Criação da linha do recibo a liquidar o documento de venda associado:

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

post

Body

application/json

Responses

200

OK

application/json

post

/commercial_sales_receipt_lines

HTTPcURLJavaScriptPython

POST /commercial_sales_receipt_lines HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 574

{
  "data": {
    "type": "commercial_sales_receipt_lines",
    "attributes": {
      "receipt_id": 1,
      "receivable_type": "text",
      "receivable_id": 1,
      "received_value": 1,
      "settlement_percentage": 1,
      "cashed_vat_amount": 1,
      "gross_total": 1,
      "settlement_amount": 1,
      "net_total": 1,
      "retention_total": 1
    },
    "relationships": {
      "receipt": {
        "data": {
          "resource": "commercial_sales_receipts"
        }
      },
      "commercial_sales_document": {
        "data": {
          "table": "receipt_lines",
          "resource": "commercial_sales_documents"
        }
      },
      "commercial_internal_sales_document_line": {
        "data": {
          "table": "receipt_lines",
          "resource": "commercial_internal_sales_document_lines"
        }
      }
    }
  }
}

200

OK

{
  "data": {
    "type": "commercial_sales_receipt_lines",
    "id": null,
    "attributes": {
      "receipt_id": 1,
      "receivable_type": "text",
      "receivable_id": 1,
      "received_value": 1,
      "settlement_percentage": 1,
      "cashed_vat_amount": 1,
      "gross_total": 1,
      "settlement_amount": 1,
      "net_total": 1,
      "retention_total": 1
    },
    "relationships": {
      "receipt": {
        "data": {
          "resource": "commercial_sales_receipts"
        }
      },
      "commercial_sales_document": {
        "data": {
          "table": "receipt_lines",
          "resource": "commercial_sales_documents"
        }
      },
      "commercial_internal_sales_document_line": {
        "data": {
          "table": "receipt_lines",
          "resource": "commercial_internal_sales_document_lines"
        }
      }
    }
  }
}

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>/commercial_sales_receipt_lines'

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

{
  "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"
    },
    "relationships": {                                            // [OBRIGATÓRIO]
      "receipt": {                                                // [OBRIGATÓRIO] Recibo a que esta linha pertence
        "data": {
          "type": "commercial_sales_receipts",                    // [OBRIGATÓRIO]
          "id": "<id do recibo>"                                  // [OBRIGATÓRIO] 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>

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

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

patch

Body

application/json

Responses

200

OK

application/json

patch

/commercial_sales_receipts

HTTPcURLJavaScriptPython

PATCH /commercial_sales_receipts HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 770

{
  "data": {
    "type": "commercial_sales_receipts",
    "attributes": {
      "id": 1,
      "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
    },
    "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"
        }
      },
      "customer": {
        "data": {
          "resource": "customers"
        }
      },
      "currency": {
        "data": {
          "resource": "currencies"
        }
      },
      "user": {
        "data": {
          "resource": "current_company_users"
        }
      },
      "lines": {
        "data": {
          "table": "receipt_lines",
          "resource": "commercial_sales_receipt_lines"
        }
      }
    },
    "id": "text"
  }
}

200

OK

{
  "data": {
    "type": "commercial_sales_receipts",
    "id": null,
    "attributes": {
      "id": 1,
      "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
    },
    "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"
        }
      },
      "customer": {
        "data": {
          "resource": "customers"
        }
      },
      "currency": {
        "data": {
          "resource": "currencies"
        }
      },
      "user": {
        "data": {
          "resource": "current_company_users"
        }
      },
      "lines": {
        "data": {
          "table": "receipt_lines",
          "resource": "commercial_sales_receipt_lines"
        }
      }
    }
  }
}

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

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

{
  "data": {
    "type": "commercial_sales_receipts",                                                      // [OBRIGATÓRIO]
    "id": "<id do recibo>",                                                                   // [OBRIGATÓRIO] Vd. NOTA 1
    "attributes": {
      "deleted": true                                                                         // [OBRIGATÓRIO]
    }
  }
}

• 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)