TOConline - Documentação API
  • Introdução
  • Setup do Postman
  • Autenticação Simplificada
  • Autenticação Detalhada
  • Características dos pedidos
  • APIs
    • Empresa
      • Clientes, Morada e E-mail
      • Fornecedores, Morada e E-mail
      • Produtos e Serviços
    • Vendas
      • Documentos de Venda
      • Documentos Retificativos
      • Recibos de Venda
      • Descarregar PDF de Documentos de Venda
      • Descarregar PDF de Recibo
      • Comunicação de documentos à AT
      • Envio de Documentos por email
      • Envio de Recibos por email
    • Compras
      • Documentos de Compra
      • Pagamentos
      • Descarregar PDF de Documentos de Compra
      • Descarregar PDF de Pagamentos
      • Comunicação de documentos à AT
    • Versões Anteriores
      • Vendas
        • Documentos de Venda
        • Recibos de Venda
      • Compras
        • Documentos de Compra
        • Pagamentos
    • APIs Auxiliares
      • Descritores de Taxa
      • Família de Itens
      • Países
      • Unidades de Medida
      • Contas Bancárias
      • Caixa Associada
      • Unidade Monetária
      • Taxas
      • Categorias de Despesa
      • Documentos de Série
Powered by GitBook
On this page
  1. APIs
  2. Versões Anteriores
  3. Vendas

Recibos de Venda

PreviousDocumentos de VendaNextCompras

Last updated 1 year ago

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. Criar Cabeçalho do Recibo de Venda

Já tem de exisitir um Documento de Venda Finalizado

Para mais informações consulte:

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

Para saber como obter mais informação de como obter o id dos Documentos de Série poderá consultar: Documentos de Série

Para saber como obter mais informação de como obter o id da Conta Bancária poderá consultar: Contas Bancárias

Para saber como obter mais informação de como obter o id da Conta de Caixa Associada poderá consultar: Caixa Associada

Payload
{ 
  "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] 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.
                    
      "document_series_id": <id do documento de série>, // [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
      
      "bank_account_id": <id da conta bancária>,// [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. Vd. Nota 2

      "cash_account_id": <id da caixa> // [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. Vd. Nota3
    }

  }
}
{
    "data": {
        "type": "commercial_sales_receipts",
        "id": "6",
        "attributes": {
            "date": "2020-06-01",
            "document_no": "RC 2023/5",
            "document_series_id": 66,
            "payment_mechanism": "MO",
            "gross_total": 0,
            "net_total": 0,
            "third_party_type": "",
            "third_party_id": null,
            "check_number": null,
            "currency_conversion_rate": 1,
            "internal_observations": null,
            "observations": null,
            "standalone": null,
            "saft_import_id": null,
            "deleted": false,
            "manual_registration_type": null,
            "manual_registration_series": null,
            "manual_registration_number": null,
            "created_at": "2024-02-26 11:31:37.827953",
            "updated_at": "2024-02-26 11:31:37.827953"
        },
        "relationships": {
            "bank_accounts": {
                "data": null
            },
            "cash_accounts": {
                "data": null
            },
            "commercial_document_series": {
                "data": {
                    "type": "commercial_document_series",
                    "id": "66"
                }
            },
            "company": {
                "data": {
                    "type": "current_company",
                    "id": "800000046"
                }
            },
            "country": {
                "data": null
            },
            "currency": {
                "data": null
            },
            "customer": {
                "data": null
            },
            "lines": {
                "data": []
            },
            "user": {
                "data": {
                    "type": "current_company_users",
                    "id": "800000863"
                }
            }
        }
    }
}

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.

Quando um documento é finalizado este vai gerar um número do documento com a estrutura [TIPO ANO/NUMERO] através deste poderá executar um filtro nos documentos de série para encontrar o seu documento.

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>

2. Criar Linha do Documento de Venda:

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

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>

3. Anular Recibo de Venda

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 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",
        "id": "3", //id do recibo de venda pretendido
        "attributes": {
            "deleted": true
        }
    }
}
{
    "data": {
        "type": "commercial_sales_receipts",
        "id": "3",
        "attributes": {
            "date": "2020-06-01",
            "document_no": "RC 2023/2",
            "document_series_id": 66,
            "payment_mechanism": "MO",
            "gross_total": 0,
            "net_total": 0,
            "third_party_type": null,
            "third_party_id": null,
            "check_number": null,
            "currency_conversion_rate": 1,
            "internal_observations": null,
            "observations": null,
            "standalone": null,
            "saft_import_id": null,
            "deleted": true,
            "manual_registration_type": null,
            "manual_registration_series": null,
            "manual_registration_number": null,
            "created_at": "2024-02-23 15:34:36.778593",
            "updated_at": "2024-02-27 12:52:10.462666"
        },
        "relationships": {
            "bank_accounts": {
                "data": null
            },
            "cash_accounts": {
                "data": null
            },
            "commercial_document_series": {
                "data": {
                    "type": "commercial_document_series",
                    "id": "66"
                }
            },
            "company": {
                "data": {
                    "type": "current_company",
                    "id": "800000046"
                }
            },
            "country": {
                "data": null
            },
            "currency": {
                "data": null
            },
            "customer": {
                "data": null
            },
            "lines": {
                "data": []
            },
            "user": {
                "data": {
                    "type": "current_company_users",
                    "id": "800000863"
                }
            }
        }
    }
}

Nota 1: O "id" interno do recibo a anular pode 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)

3. Finalização do documento

Anular Recibo de Venda

patch

Anular Recibo de Venda

Authorizations
Path parameters
salesReceiptIdstringRequired
Responses
200Success
patch
PATCH /api/v1/commercial_sales_receipts/{salesReceiptId}/void HTTP/1.1
Host: {{base_url}}
Accept: */*
200Success

No content

  • Criação de recibos
  • 1. Criar Cabeçalho do Recibo de Venda
  • POSTCriar Cabeçalho de Recibo de Venda
  • 2. Criar Linha do Documento de Venda:
  • POSTAdicionar Linha a Recibo de Venda
  • 3. Anular Recibo de Venda
  • PATCHAnular Recibo de Venda

Criar Cabeçalho de Recibo de Venda

post

Criar Cabeçalho de Recibo de Venda

Authorizations
Body
Responses
200Success
post
POST /api/commercial_sales_receipts HTTP/1.1
Host: {{base_url}}
Content-Type: application/json
Accept: */*
Content-Length: 161

{
  "data": {
    "attributes": {
      "date": "2025-06-01",
      "document_series_id": 66,
      "gross_total": 10,
      "net_total": 20,
      "payment_mechanism": "MO"
    },
    "type": "commercial_sales_receipts"
  }
}
200Success

No content

Adicionar Linha a Recibo de Venda

post

Adicionar Linha a Recibo de Venda

Authorizations
Body
Responses
200Success
post
POST /api/commercial_sales_receipt_lines HTTP/1.1
Host: {{base_url}}
Content-Type: application/json
Accept: */*
Content-Length: 285

{
  "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"
  }
}
200Success

No content