# Introdução

## Seja bem-vindo à nossa API - CloudInvoice

Seja Bem-Vindo à nova documentação da nossa API de acesso ao CloudInvoice.\
Esta será a nova documentação de acesso à sua empresa.

Para mais informação, por favor [Contacte-nos](https://www.cloudinvoice.net/contact_us) através dos canais disponíveis.

## Ainda não tem Conta?

* [Registe-se e Experimente Grátis](https://www.cloudinvoice.net/accounts/signup/)
* Obtenha um Token de Acesso à API
* Utilize a API para consultar ou criar documentos, clientes, produtos e muito mais...

## Quem pode utilizar a API?

A [API](https://pt.wikipedia.org/wiki/Interface_de_programa%C3%A7%C3%A3o_de_aplica%C3%A7%C3%B5es) CloudInvoice dá-lhe a oportunidade de interagir com a sua conta CloudInvoice a partir de aplicações externas. Existe para permitir e facilitar o processo de criação de aplicações web e desktop que se desejem integrar e interagir com o CloudInvoice.\
\
Qualquer utilizador registado no CloudInvoice poderá ter acesso à API, limitado pelas permissões dadas pelos seus administradores de empresa. De acordo com o plano da empresa, poderá ter acesso limitado a algumas funcionalidades da API. Para confirmar quais as funcionalidades disponíveis, poderá sempre consultar os nossos [planos](https://www.cloudinvoice.net/pricing) e as suas características.

{% content-ref url="/pages/KFE2bTd36NoAN23PIsqk" %}
[Começar a Utilizar](/introducao/comecar-a-utilizar)
{% endcontent-ref %}

## Obter Token de Acesso

Para iniciar a comunicação com a nossa API deve começar por gerar um token de acesso para a sua empresa através do seu username / password.

{% content-ref url="/pages/aSptHFKp7hvKgybJHCLJ" %}
[Conta / Autenticação](/conta-autenticacao)
{% endcontent-ref %}


# Começar a Utilizar

## Funcionamento

A API CloudInvoice funciona com pedidos HTTP normais em `GET` ou `POST`, que poderão ser realizados a partir de qualquer ferramenta própria (como cURL, HTTPie, qualquer REST client ou mesmo Ajax), sendo o conteúdo do pedido (para pedidos `POST`) em formato [JSON](https://pt.wikipedia.org/wiki/JSON).

```url
https://api.cloudinvoice.net/customers/
```

{% hint style="info" %}
Importante: Tanto a API como esta documentação estão em constante desenvolvimento. É possível que hajam entradas em falta na documentação que já existem na API assim como Endpoints da API cuja existência melhoraria grandemente a experiência de quem usar a API. 

[Contacte-nos](http://localhost:8000/contact_us/) para saber como deixar as suas sugestões.
{% endhint %}


# Autenticação

{% hint style="info" %}
Para aceder à API, um token de acesso deverá ser usado. Um Token está associado a um Utilizador autenticado numa Localização, num Terminal e numa Caixa, na sua empresa. Tudo o que for feito usando um Token, terá a autoria atribuída ao utilizador associado e reger-se-á pelas suas permissões na aplicação.
{% endhint %}

## A criação de Tokens pode ser feita de duas maneiras:

* BackOffice: Poderá criar Tokens acedendo ao BackOffice, em Empresa  Tokens de Acesso à API, onde poderá atribuir o Token a um Utilizador, Localização e Terminal.
* Usando a própria API: Pode obter um Token fazendo um pedido ao end-point `/auth/login`, incluindo as suas credenciais de autenticação, obtendo na resposta o Token que poderá utilizar nos pedidos posteriores.

## Login

## Gera um Token de Acesso para as credenciais fornecidas:

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/auth/login/`

#### Request Body

| Name                                       | Type   | Description |
| ------------------------------------------ | ------ | ----------- |
| username<mark style="color:red;">\*</mark> | email  |             |
| password<mark style="color:red;">\*</mark> | string |             |
| company\_code                              | string |             |
| till\_code                                 | string |             |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/auth/login/
    -d '{
        "username": "user@sample.com",
        "password": "pFS2VwMk"
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "key": "329c2d5cadd96ccce7b0b0f2653e8d08f61ddd52"
}

```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Para além das credenciais username/password, pode também incluir a Empresa **`company_code`** e a Caixa **`till_code`** a que pretende associar o token de acesso.
{% endhint %}

## Pedidos com Autenticação

Para efectuar pedidos com autenticação, deverá usar um dos seguintes métodos:

* Incluir o Header HTTP: `Authorization: Token <token>`

```shell
curl https://api.cloudinvoice.net/customers/
    -H "Content-Type: application/json"
    -H "Authorization: Token 329c2d5cadd96ccce7b0b0f2653e8d08f61ddd52"
```

* Incluir o Query Param: `api_token=<token>`

```shell
curl https://api.cloudinvoice.net/customers/?api_token=329c2d5cadd96ccce7b0b0f2653e8d08f61ddd52
    -H "Content-Type: application/json"
```

{% hint style="info" %}
Em pedidos **`POST`** deve incluir sempre o&#x20;

Header: **`Content-Type: application/json;`**
{% endhint %}


# Exemplos de Pedidos

Os pedidos são feitos ao endereço `https://api.cloudinvoice.net/`, acrescentando-lhe o end-point da acção pretendida. Nesta documentação, usaremos pedidos realizados a partir do software [cURL](https://curl.haxx.se/) como exemplo.

## Exemplos de Pedidos à API:

### Curl

```shell
curl https://api.cloudinvoice.net/customers/
    -H "Content-Type: application/json"
    -H "Authorization: Token 329c2d5cadd96ccce7b0b0f2653e8d08f61ddd52"
```

### Python

```python
import http.client

conn = http.client.HTTPSConnection("api.cloudinvoice.net")
headers = { 'Authorization': 'Token 329c2d5cadd96ccce7b0b0f2653e8d08f61ddd52', 'Content-Type': 'application/json' }

conn.request("GET", "/customers/", headers=headers)

res = conn.getresponse()
data = res.read().decode('utf-8')
json_data = json.loads(data)
print(json_data)
```

### Node

```javascript
const https = require("https");

var options = {
  "hostname": "api.cloudinvoice.net",
  "path": "/customers/",
  "port": null,
  "method": "GET",
  "headers": {
    "Authorization": "Token 329c2d5cadd96ccce7b0b0f2653e8d08f61ddd52",
    "Content-Type": "application/json"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    var bodyStr = body.toString();
    var bodyJson = JSON.parse(bodyStr);
  });
});

req.end();
```

### Ruby

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.cloudinvoice.net/customers/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["Authorization"] = "Token 329c2d5cadd96ccce7b0b0f2653e8d08f61ddd52"
request["Content-Type"] = "application/json"

response = http.request(request)
puts response.read_body
```

### PHP

```php
<?php

$url = 'https://api.cloudinvoice.net/customers/';
$token = "329c2d5cadd96ccce7b0b0f2653e8d08f61ddd52";
$headers = array(
    'Content-Type: application/json',
    'Authorization: Token '.$token,
);

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_POST, false);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #:" . $err;
} else {
    $result = json_decode($response, true);
    echo $result;
}
```

### Go

```go
package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {
    url := "https://api.cloudinvoice.com/customers/"

    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Add("Authorization", "Token 329c2d5cadd96ccce7b0b0f2653e8d08f61ddd52")
    req.Header.Add("Content-Type", "application/json")
    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))
}
```


# Erros e Respostas

## Possíveis Status & Respostas

<table><thead><tr><th width="136" data-type="number">STATUS</th><th>DESCRIÇÃO</th><th>RESULTADO</th></tr></thead><tbody><tr><td>200</td><td><strong>Success</strong><br>Pedido efectuado com sucesso</td><td>Lista de registos encontrados</td></tr><tr><td>201</td><td><strong>Created</strong><br>Registo criado com sucesso</td><td>GET Registo</td></tr><tr><td>204</td><td><strong>No Content</strong><br>Pedido processado com sucesso mas sem resposta.</td><td>(Sem Resposta)</td></tr><tr><td>400</td><td><strong>Bad Request</strong><br>Existem parâmetros inválidos ou inexistentes.</td><td>Lista de erros detectados</td></tr><tr><td>401</td><td><strong>Access Denied</strong><br>Token inválido ou inexistente</td><td>(Sem Resposta)</td></tr><tr><td>403</td><td><strong>Forbidden</strong><br>Não tem permissões para aceder a este endpoint.</td><td>(Sem Resposta)</td></tr><tr><td>404</td><td><strong>Not Found</strong><br>Registo não encontrado.</td><td>(Sem Resposta)</td></tr><tr><td>405</td><td><strong>Method Not Allowed</strong><br>Método não é permitido para este endpoint.</td><td>(Sem Resposta)</td></tr></tbody></table>

## Exemplo de Resposta com Erro

Em caso de erro, qualquer que seja o tipo de erro, a API CloudInvoice responde, habitualmente, com um código `400 Bad Request`.

```json
{
    "errors": [
        {
            "message": "Este campo deve ser um inteiro",
            "code": "invalid",
            "field": "code"
        },
        {
            "message": "Este campo é obrigatório.",
            "code": "invalid",
            "field": "customer_name"
        }
    ]
}
```

<br>


# Precisa de Ajuda?

Estamos aqui para o ajudar. A nossa API é uma ferramenta em constante desenvolvimento para ir, tanto quanto possível, ao encontro do que os nossos utilizadores precisam.

Agradecemos o report de qualquer bug, problema ou mesmo sugestões para melhorar a nossa API para o e-mail <suporte@cloudinvoice.net>

Se não encontrou o que procurava na documentação ou achou pouco explícito e ainda assim precisa da nossa ajuda, contacte-nos para o e-mail <suporte@cloudinvoice.net> ou através dos nossos [canais disponíveis](https://www.cloudinvoice.net/contact_us/).\
Teremos todo o gosto em ajudar no que for possível.


# Change Log

Tanto a API como esta documentação estão em constante desenvolvimento. É possível que hajam entradas em falta na documentação que já existem na API assim como endpoints da API cuja existência melhoraria grandemente a experiência de quem usar a API.&#x20;

[Contacte-nos](https://www.cloudinvoice.net/contact_us/) para saber como deixar as suas sugestões.

### 11 de Janeiro 2023

* Lançamento da API externa /api

### 20 de Agosto 2022

* Lançamento da API interna /v3

### 15 de Setembro 2021

* Lançamento da API interna /v2


# Conta / Autenticação

{% hint style="info" %}
Aqui pode gerar e consultar os tokens de acesso tanto às suas empresas como a uma empresa de demonstração, para testar e experimentar. Pode consultar todos os dados relacionados com o utilizador autenticado e associado ao token. Consulte os seus dados pessoais, empresas, planos de demonstração, etc...
{% endhint %}


# Login

{% hint style="info" %}
Este endpoint não requer autenticação.
{% endhint %}

## Criar Token de Acesso

## Gera um Token de Acesso para as credenciais fornecidas:

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/auth/login/`

#### Request Body

| Name                                       | Type   | Description            |
| ------------------------------------------ | ------ | ---------------------- |
| username<mark style="color:red;">\*</mark> | email  | Email do Utilizador    |
| password<mark style="color:red;">\*</mark> | string | Password do Utilizador |
| company\_code                              | string | Código da Empresa      |
| till\_code                                 | string | Código da Caixa        |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/auth/login/
    -d '{
        "username": "user@sample.com",
        "password": "pFS2VwMk"
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "key": "329c2d5cadd96ccce7b0b0f2653e8d08f61ddd52"
}

```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Para além das credenciais username/password, pode também incluir a Empresa **`company_code`** e a Caixa **`till_code`** a que pretende associar o token de acesso.
{% endhint %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Login - Sandbox

{% hint style="info" %}
Este endpoint não requer autenticação.
{% endhint %}

## Criar Token de Acesso a Sandbox (Demonstração)

## Gera um Token de Acesso para a fins de demonstração:

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/auth/login_sandbox/`

#### Request Body

| Name                                       | Type    | Description                     |
| ------------------------------------------ | ------- | ------------------------------- |
| username<mark style="color:red;">\*</mark> | email   | Email do Utilizador             |
| password<mark style="color:red;">\*</mark> | string  | Password do Utilizador          |
| demo\_plan\_id                             | integer | Plano de Demonstração           |
| demo\_plan\_code                           | string  | Código do Plano de Demonstração |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/auth/login_sandbox/
    -d '{
        "username": "user@sample.com",
        "password": "pFS2VwMk"
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "key": "329c2d5cadd96ccce7b0b0f2653e8d08f61ddd52"
}

```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Pode consultar os planos disponíveis para demonstração em [Planos Demo](https://www.cloudinvoice.net/api_documentation/account/demo_plan/).
{% endhint %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Planos Demo

{% hint style="info" %}
Este endpoint não requer autenticação.
{% endhint %}

## Lista de Planos para Demontração

## Devolve lista dos planos disponíveis para demonstração.

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/auth/demo_plan/`

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/auth/demo_plan/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
[
    {
        "id": 1,
        "code": "INDIVIDUAL",
        "description": "Plano Individual"
    },
    {
        "id": 2,
        "code": "SERVICES",
        "description": "Plano Facturação de Serviços"
    },
    {
        "id": 3,
        "code": "RETAIL",
        "description": "Plano Gestão de Loja"
    },
    {
        "id": 4,
        "code": "BUSINESS",
        "description": "Plano Gestão Comercial"
    }
]
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Info do User

## Informações do Utilizador

## Devolve informação sobre o token de acesso, como utilizador, empresa, terminal, etc...

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/auth/info/`

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/auth/demo_plan/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "updated_at": 1613150982,
    "version": "1.0.0",
    "version_date": "2021-01-08",
    "today_str": "2021-02-12",
    "created": "2021-02-03T18:34:55.548535Z",
    "key": "16511f6558a00e3273d8b4882b9d9ccdc57cbe4d",
    "user": {
        "id": 1,
        "first_name": "Sample",
        "last_name": "User",
        "full_name": "Sample User",
        "is_active": true,
        "is_staff": false,
        ...
    },
    "company": {
        "id": 1,
        "code": "demo_company",
        ...
    },
    ...
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Empresas

## Lista de Empresas

## Devolve lista das empresas associadas ao utilizador do token.

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/auth/companies/`

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/auth/companies/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
[
    {
        "id": 1,
        "code": "demo",
        "company_name": "Empresa Demo",
        "is_staff": true,
        "is_salesman": false,
        "is_demo": true,
        "tills": [
            {
                "id": 1,
                "description": "Caixa 1",
                "code": 1,
                "terminal_id": 1,
                "terminal": "Terminal 1",
                "location_id": 1,
                "location": "Localização 1"
            }
        ],
        "last_location_id": 1,
        "last_terminal_id": 1,
        "last_till_id": 1
    },
    ...
]
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Documentos

Emita Facturas, Facturas-Simplificadas, Facturas-Recibo, Notas de Crédito, Encomendas a clientes e faça a gestão de contas-correntes.

{% hint style="info" %}
Notas: Os endpoints relacionados com os documentos incluem apenas as naturezas de vendas, stocks, transporte e outros documentos relacionados, tais como, orçamentos, notas de encomenda, etc...
{% endhint %}


# List

Fornece uma lista dos documentos existentes.

## Listar Documentos

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/documents/`

#### Query Parameters

| Name             | Type    | Description                                                                                                                                                                                                                                                                                            |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| limit            | integer | Define o número de registos por pesquisa.                                                                                                                                                                                                                                                              |
| offset           | integer | <p>Indica a posição inicial da pesquisa.</p><p>Retorna a lista de registos compreendida entre <code>offset</code> e <code>offset+limit</code>.</p>                                                                                                                                                     |
| ordering         | string  | <p>Define o campo e a direção a usar na pesquisa de registos. </p><p></p><p>Campos ordenáveis:</p><ul><li><code>id</code>, <code>doc\_key</code>, <code>document\_date</code>, <code>document\_time</code></li></ul><p>Use '-' antes do nome para ordem decresente.</p>                                |
| search           | string  | <p>Define o termo de pesquisa a utilizar na lista de registos. </p><p></p><p>Campos Pesquisados:</p><ul><li><code>doc\_key</code>, <code>document\_name</code>, <code>our\_reference</code>, <code>party\_fiscal\_number</code>, <code>party\_name</code>, <code>salesman\_name</code>, etc.</li></ul> |
| document\_nature | integer | <p>Natureza do Documento</p><p></p><p>Consulte a tabela <a href="/documentacao-api/apendice#naturezas-de-documentos-campo-document_nature">Apêndice</a> para mais informação</p>                                                                                                                       |
| document\_status | integer | <p>Estado do Documento</p><p></p><p>Consulte a tabela <a href="/documentacao-api/apendice#estados-dos-documentos-campo-document_status">Apêndice</a> para mais informação</p>                                                                                                                          |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/documents/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "limit": 10,
    "offset": 0,
    "count": 3279,
    "next": "https://api.cloudinvoice.net/documents/?limit=10&offset=10",
    "previous": null,
    "results":[
        {
            "id": 1,
            "doc_key": "FSI A01/1",
            "document_date": "2023-01-10",
            "document_time": "11:30:48.700759",
            "document_number": 1,
            "our_reference": "",
            "is_valued": true,
            "total_amount": 54.9,
            "total_due_amount": 0.0,
            "due_date": "2023-01-10",
            "document_id": 2,
            "document": {
                "code": "FSI", 
                "document_name": "Factura Simplificada"
            },
            "document_serie_id": 1,
            "document_serie": {
                "code": "A01", 
                "description": "Série A01"
            },
            "document_status_id": 1202,
            "document_status": {
                "code": "F", 
                "description": "Finalizado"
            },
            "warehouse_id": 1,
            "warehouse": {
                "code": 1, 
                "description": "Armazém 1"
            },
            "document_nature_id": 302,
            "document_nature": {
                "code": "FS", 
                "description": "Factura Simplificada"
            },
            "party_id": 1,
            "party": {
                "class": 1601, 
                "code": 1, 
                "name": "Consumidor Final", 
                "fiscal_number": "999999990"
            }
        },
        ...
    ]
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)

{% hint style="info" %}
**Notas:** Alguns dos campos do termo de pesquisa geral poderão ser incluídos mediante critérios específicos (Ex: Descrição será incluída na pesquisa geral apenas se o termo de pesquisa contiver 3 ou mais caracteres). Por defeito, o comportamento expectável será obter-se todos os items cujo o texto a pesquisar (search) esteja CONTIDO em pelo menos um dos campos incluídos na pesquisa geral.
{% endhint %}


# Vendas

Fornece uma lista das vendas existentes.

## Listar Vendas

{% hint style="info" %}
Nesta lista estão incluídas as seguintes naturezas: Facturas, Facturas-Recibo, Facturas-Simplificadas, Notas de Crédito e Notas de Débito.
{% endhint %}

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/documents/sales/`

#### Query Parameters

| Name             | Type    | Description                                                                                                                                                                                                                                                                                            |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| limit            | integer | Define o número de registos por pesquisa.                                                                                                                                                                                                                                                              |
| offset           | integer | <p>Indica a posição inicial da pesquisa.</p><p>Retorna a lista de registos compreendida entre <code>offset</code> e <code>offset+limit</code>.</p>                                                                                                                                                     |
| ordering         | string  | <p>Define o campo e a direção a usar na pesquisa de registos. </p><p></p><p>Campos ordenáveis:</p><ul><li><code>id</code>, <code>doc\_key</code>, <code>document\_date</code>, <code>document\_time</code></li></ul><p>Use '-' antes do nome para ordem decrescente.</p>                               |
| search           | string  | <p>Define o termo de pesquisa a utilizar na lista de registos. </p><p></p><p>Campos Pesquisados:</p><ul><li><code>doc\_key</code>, <code>document\_name</code>, <code>our\_reference</code>, <code>party\_fiscal\_number</code>, <code>party\_name</code>, <code>salesman\_name</code>, etc.</li></ul> |
| document\_nature | integer | <p>Natureza do Documento</p><p></p><p>Consulte a tabela <a href="/documentacao-api/apendice#naturezas-de-documentos-campo-document_nature">Apêndice</a> para mais informação</p>                                                                                                                       |
| document\_status | integer | <p>Estado do Documento</p><p></p><p>Consulte a tabela <a href="/documentacao-api/apendice#estados-dos-documentos-campo-document_status">Apêndice</a> para mais informação</p>                                                                                                                          |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/documents/sales/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "limit": 10,
    "offset": 0,
    "count": 100,
    "next": "https://api.cloudinvoice.net/documents/sales/?limit=10&offset=10",
    "previous": null,
    "results":[
        {
            "id": 1,
            "doc_key": "FSI A01/1",
            "document_date": "2023-01-10",
            "document_time": "11:30:48.700759",
            "document_number": 1,
            "our_reference": "",
            "is_valued": true,
            "total_amount": 54.9,
            "total_due_amount": 0.0,
            "due_date": "2023-01-10",
            "document_id": 2,
            "document": {
                "code": "FSI", 
                "document_name": "Factura Simplificada"
            },
            "document_serie_id": 1,
            "document_serie": {
                "code": "A01", 
                "description": "Série A01"
            },
            "document_status_id": 1202,
            "document_status": {
                "code": "F", 
                "description": "Finalizado"
            },
            "warehouse_id": 1,
            "warehouse": {
                "code": 1, 
                "description": "Armazém 1"
            },
            "document_nature_id": 302,
            "document_nature": {
                "code": "FS", 
                "description": "Factura Simplificada"
            },
            "party_id": 1,
            "party": {
                "class": 1601, 
                "code": 1, 
                "name": "Consumidor Final", 
                "fiscal_number": "999999990"
            }
        },
        ...
    ]
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)

{% hint style="info" %}
**Notas:** Alguns dos campos do termo de pesquisa geral poderão ser incluídos mediante critérios específicos (Ex: Descrição será incluída na pesquisa geral apenas se o termo de pesquisa contiver 3 ou mais caracteres). Por defeito, o comportamento expectável será obter-se todos os items cujo o texto a pesquisar (search) esteja CONTIDO em pelo menos um dos campos incluídos na pesquisa geral.
{% endhint %}


# Guias

Fornece uma lista das guias existentes.

## Listar Guias

{% hint style="info" %}
Nesta lista estão incluídas as seguintes naturezas: Guias de Remessa e Guias de Transporte.
{% endhint %}

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/documents/sales_guides/`

#### Query Parameters

| Name             | Type    | Description                                                                                                                                                                                                                                                                                            |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| limit            | integer | Define o número de registos por pesquisa.                                                                                                                                                                                                                                                              |
| offset           | integer | <p>Indica a posição inicial da pesquisa.</p><p>Retorna a lista de registos compreendida entre <code>offset</code> e <code>offset+limit</code>.</p>                                                                                                                                                     |
| ordering         | string  | <p>Define o campo e a direção a usar na pesquisa de registos. </p><p></p><p>Campos ordenáveis:</p><ul><li><code>id</code>, <code>doc\_key</code>, <code>document\_date</code>, <code>document\_time</code></li></ul><p>Use '-' antes do nome para ordem decrescente.</p>                               |
| search           | string  | <p>Define o termo de pesquisa a utilizar na lista de registos. </p><p></p><p>Campos Pesquisados:</p><ul><li><code>doc\_key</code>, <code>document\_name</code>, <code>our\_reference</code>, <code>party\_fiscal\_number</code>, <code>party\_name</code>, <code>salesman\_name</code>, etc.</li></ul> |
| document\_nature | integer | <p>Natureza do Documento</p><p></p><p>Consulte a tabela <a href="/documentacao-api/apendice#naturezas-de-documentos-campo-document_nature">Apêndice</a> para mais informação</p>                                                                                                                       |
| document\_status | integer | <p>Estado do Documento</p><p></p><p>Consulte a tabela <a href="/documentacao-api/apendice#estados-dos-documentos-campo-document_status">Apêndice</a> para mais informação</p>                                                                                                                          |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/documents/sales_guides/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

<pre class="language-json"><code class="lang-json">{
<strong>    "limit": 10,
</strong>    "offset": 0,
    "count": 56,
    "next": "https://api.cloudinvoice.net/documents/sales_guides/?limit=10&#x26;offset=10",
    "previous": null,
    "results":[
        {
            "id": 1,
            "doc_key": "GRE A01/1",
            "document_date": "2022-12-15",
            "document_time": "00:03:20.270569",
            "document_number": 1,
            "our_reference": "",
            "is_valued": true,
            "total_amount": 2.0,
            "total_due_amount": 0.0,
            "due_date": "2022-12-15",
            "document_nature_id": 321,
            "document_id": 8,
            "document": {
                "code": "GRE", 
                "document_name": "Guia de Remessa"
            },
            "document_serie_id": 1,
            "document_serie": {
                "code": "A01", 
                "description": "Série A01"
            },
            "document_status_id": 1202,
            "warehouse_id": 1,
            "warehouse": {
                "code": 1, 
                "description": "Armazém 1"
            },
            "document_nature": {
                "code": "GR", 
                "description": "Guia de Remessa"
            },
            "document_status": {
                "code": "F", 
                "description": "Finalizado"
            },
            "party_id": 39,
            "party": {
                "class": 1601, 
                "code": 1023, 
                "name": "Cliente Demo", 
                "fiscal_number": "999999990"
            }
        },
        ...
    ]
}
</code></pre>

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)

{% hint style="info" %}
**Notas:** Alguns dos campos do termo de pesquisa geral poderão ser incluídos mediante critérios específicos (Ex: Descrição será incluída na pesquisa geral apenas se o termo de pesquisa contiver 3 ou mais caracteres). Por defeito, o comportamento expectável será obter-se todos os items cujo o texto a pesquisar (search) esteja CONTIDO em pelo menos um dos campos incluídos na pesquisa geral.
{% endhint %}


# Movimentações de Stock

Fornece uma lista dos documentos de stock existentes.

## Listar Documentos de Stock

{% hint style="info" %}
Nesta lista estão incluídas as seguintes naturezas: Entradas de Stock, Saídas de Stock e Transferências de Armazém.
{% endhint %}

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/documents/stocks/`

#### Query Parameters

| Name             | Type    | Description                                                                                                                                                                                                                                                                                            |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| limit            | integer | Define o número de registos por pesquisa.                                                                                                                                                                                                                                                              |
| offset           | integer | <p>Indica a posição inicial da pesquisa.</p><p>Retorna a lista de registos compreendida entre <code>offset</code> e <code>offset+limit</code>.</p>                                                                                                                                                     |
| ordering         | string  | <p>Define o campo e a direção a usar na pesquisa de registos. </p><p></p><p>Campos ordenáveis:</p><ul><li><code>id</code>, <code>doc\_key</code>, <code>document\_date</code>, <code>document\_time</code></li></ul><p>Use '-' antes do nome para ordem decrescente.</p>                               |
| search           | string  | <p>Define o termo de pesquisa a utilizar na lista de registos. </p><p></p><p>Campos Pesquisados:</p><ul><li><code>doc\_key</code>, <code>document\_name</code>, <code>our\_reference</code>, <code>party\_fiscal\_number</code>, <code>party\_name</code>, <code>salesman\_name</code>, etc.</li></ul> |
| document\_nature | integer | <p>Natureza do Documento</p><p></p><p>Consulte a tabela <a href="/documentacao-api/apendice#naturezas-de-documentos-campo-document_nature">Apêndice</a> para mais informação</p>                                                                                                                       |
| document\_status | integer | <p>Estado do Documento</p><p></p><p>Consulte a tabela <a href="/documentacao-api/apendice#estados-dos-documentos-campo-document_status">Apêndice</a> para mais informação</p>                                                                                                                          |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/documents/stocks/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

<pre class="language-json"><code class="lang-json">{
<strong>    "limit": 10,
</strong>    "offset": 0,
    "count": 56,
    "next": "https://api.cloudinvoice.net/documents/stocks/?limit=10&#x26;offset=10",
    "previous": null,
    "results":[
        {
            "id": 1,
            "doc_key": "EST A01/1",
            "document_date": "2022-09-28",
            "document_time": "17:41:13.251893",
            "document_number": 1,
            "our_reference": "",
            "is_valued": true,
            "total_amount": 1707.3,
            "total_due_amount": 0.0,
            "due_date": "2022-09-28",
            "document_nature_id": 502,
            "document_id": 38,
            "document": {
                "code": "EST", 
                "document_name": "Entrada de Stock"
            },
            "document_serie_id": 1,
            "document_serie": {
                "code": "A01", 
                "description": "Série A01"
            },
            "document_status_id": 1201,
            "warehouse_id": 1,
            "warehouse": {
                "code": 1, 
                "description": "Armazém 1"
            },
            "document_nature": {
                "code": "EST", 
                "description": "Entrada de Stock"
            },
            "document_status": {
                "code": "F", 
                "description": "Finalizado"
            },
            "party_id": null,
            "party": null
        },
        ...
    ]
}
</code></pre>

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)

{% hint style="info" %}
**Notas:** Alguns dos campos do termo de pesquisa geral poderão ser incluídos mediante critérios específicos (Ex: Descrição será incluída na pesquisa geral apenas se o termo de pesquisa contiver 3 ou mais caracteres). Por defeito, o comportamento expectável será obter-se todos os items cujo o texto a pesquisar (search) esteja CONTIDO em pelo menos um dos campos incluídos na pesquisa geral.
{% endhint %}


# Outros Documentos

Fornece uma lista dos outros documentos existentes.

## Listar Outros Documentos

{% hint style="info" %}
Nesta lista estão incluídas as seguintes naturezas: Orçamentos, Notas de Encomenda e Folhas de Obra.&#x20;
{% endhint %}

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/documents/working_documents/`

#### Query Parameters

| Name             | Type    | Description                                                                                                                                                                                                                                                                                            |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| limit            | integer | Define o número de registos por pesquisa.                                                                                                                                                                                                                                                              |
| offset           | integer | <p>Indica a posição inicial da pesquisa.</p><p>Retorna a lista de registos compreendida entre <code>offset</code> e <code>offset+limit</code>.</p>                                                                                                                                                     |
| ordering         | string  | <p>Define o campo e a direção a usar na pesquisa de registos. </p><p></p><p>Campos ordenáveis:</p><ul><li><code>id</code>, <code>doc\_key</code>, <code>document\_date</code>, <code>document\_time</code></li></ul><p>Use '-' antes do nome para ordem decrescente.</p>                               |
| search           | string  | <p>Define o termo de pesquisa a utilizar na lista de registos. </p><p></p><p>Campos Pesquisados:</p><ul><li><code>doc\_key</code>, <code>document\_name</code>, <code>our\_reference</code>, <code>party\_fiscal\_number</code>, <code>party\_name</code>, <code>salesman\_name</code>, etc.</li></ul> |
| document\_nature | integer | <p>Natureza do Documento</p><p></p><p>Consulte a tabela <a href="/documentacao-api/apendice#naturezas-de-documentos-campo-document_nature">Apêndice</a> para mais informação</p>                                                                                                                       |
| document\_status | integer | <p>Estado do Documento</p><p></p><p>Consulte a tabela <a href="/documentacao-api/apendice#estados-dos-documentos-campo-document_status">Apêndice</a> para mais informação</p>                                                                                                                          |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/documents/working_documents/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

<pre class="language-json"><code class="lang-json">{
<strong>    "limit": 10,
</strong>    "offset": 0,
    "count": 56,
    "next": "https://api.cloudinvoice.net/documents/working_documents/?limit=10&#x26;offset=10",
    "previous": null,
    "results":[
        {
            "id": 1,
            "doc_key": "ORC A01/1",
            "document_date": "2022-12-19",
            "document_time": "17:45:58.955479",
            "document_number": 1,
            "our_reference": "",
            "is_valued": true,
            "total_amount": 2.46,
            "total_due_amount": 0.0,
            "due_date": "2022-12-19",
            "document_nature_id": 353,
            "document_id": 20,
            "document": {
                "code": "ORC",
                "document_name": "Orçamento"
            },
            "document_serie_id": 1,
            "document_serie": {
                "code": "A01",
                "description": "Série A01"
            },
            "document_status_id": 1202,
            "warehouse_id": 1,
            "warehouse": {
                "code": 1,
                "description": "Armazém 1"
            },
            "document_nature": {
                "code": "OR",
                "description": "Orçamento"
            },
            "document_status": {
                "code": "F",
                "description": "Finalizado"
            },
            "party_id": 9,
            "party": {
                "class": 1601,
                "code": 9,
                "name": "Cliente Demo",
                "fiscal_number": "999999990"
            }
        },
        ...
    ]
}
</code></pre>

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)

{% hint style="info" %}
**Notas:** Alguns dos campos do termo de pesquisa geral poderão ser incluídos mediante critérios específicos (Ex: Descrição será incluída na pesquisa geral apenas se o termo de pesquisa contiver 3 ou mais caracteres). Por defeito, o comportamento expectável será obter-se todos os items cujo o texto a pesquisar (search) esteja CONTIDO em pelo menos um dos campos incluídos na pesquisa geral.
{% endhint %}


# Create

Cria um novo documento.

## Criar Documento

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/documents/new/`

#### Request Body

<table data-search="false"><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>document_id</td><td>integer</td><td><p>Tipo de Documento</p><p></p><p>Consulte a tabela <a href="/documentacao-api/tipos-de-documentos/list">Tipos de Documentos</a>.</p></td></tr><tr><td>document_nature_id</td><td>integer</td><td><p>Natureza do Documento</p><p></p><p><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> obrigatório se  o campo <code>document_id</code> não for fornecido.</p><p></p><p>Consulte a tabela <a href="/documentacao-api/apendice#naturezas-de-documentos-campo-document_nature">Apêndice</a>.</p></td></tr><tr><td>document_nature_code</td><td>string</td><td><p>Código da Natureza do Documento</p><p></p><p><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Este parâmetro substitui <code>document_nature_id</code></p><p></p><p>Consulte a tabela <a href="/documentacao-api/apendice#naturezas-de-documentos-campo-document_nature">Apêndice</a> para saber mais.</p></td></tr><tr><td>document_serie_id</td><td>integer</td><td><p>Série de Documentos</p><p></p><p>Consulte a tabela <a href="/documentacao-api/series-de-documentos/list">Séries</a>.</p><p></p><p><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Apenas surtirá efeito quando submetido em simultâneo com o campo <code>document_id</code>.</p></td></tr><tr><td>document_date</td><td>date<br><sub><mark style="color:$info;">Format: yyyy-mm-dd</mark></sub></td><td>Data de Emissão<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Documentos de relevância fiscal (assinados) poderão ignorar este valor.</td></tr><tr><td>document_time</td><td>time<br><sub><mark style="color:$info;">Format: hh:mm:ss</mark></sub></td><td>Hora de Emissão<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Documentos de relevância fiscal (assinados) poderão ignorar este valor.</td></tr><tr><td>is_tax_included</td><td>boolean</td><td><p>Definir valores c/IVA Incluído.</p><p>Caso não defina, será usado de acordo com a configuração do documento.</p></td></tr><tr><td>party_class</td><td>integer</td><td><p>Classe de Entidade<br></p><p>Apenas em casos muito especííficos poderá ser necessário fornecer este valor. Por norma, este é deduzido da natureza do Documento usado.</p><p><br>Consulte a tabela <a href="/documentacao-api/apendice#classes-de-entidades-campo-party_class">Apêndice</a>.</p></td></tr><tr><td>party_id</td><td>integer</td><td><p>Entidade</p><p></p><p>Consulte a tabela <a href="/documentacao-api/clientes/list">Clientes</a>.</p></td></tr><tr><td>party_fiscal_number</td><td>string</td><td>NIF da Entidade</td></tr><tr><td>warehouse_id</td><td>integer</td><td>Armazém<br><br>Consulte Tabela Armazéns no Backoffice.</td></tr><tr><td>price_line_id</td><td>integer</td><td><p>Linha de Preços</p><p></p><p>Consulte a tabela <a href="/documentacao-api/linhas-de-precos/list#lista-de-linhas-de-precos">Linhas de Preços</a>.</p></td></tr><tr><td>our_reference</td><td>string</td><td>Nossa Referência.</td></tr><tr><td>document_reference</td><td>string</td><td><p>Referência do Documento</p><p></p><p>Este campo poderá ser de preenchimento obrigatório (ex: doc. de compra).</p></td></tr><tr><td>salesman_id</td><td>integer</td><td><p>Vendedor</p><p></p><p>Consulte a tabela de <a href="/documentacao-api/vendedores/list">Vendedores</a>.</p></td></tr><tr><td>payment_term_id</td><td>integer</td><td><p>Condição de Pagamento</p><p></p><p>Consulte a tabela <a href="/documentacao-api/condicoes-de-pagamento/list#lista-de-condicoes-de-pagamento">Condições de Pagamento</a> para saber mais.</p></td></tr><tr><td>global_discount1</td><td>float</td><td><p>Desconto Global</p><p>Valores entre 0 e 100.</p></td></tr><tr><td>details</td><td>array</td><td><p>Linhas do Documento</p><p></p><p>Deverá conter uma lista de objetos, sendo que cada objeto poderá conter os parâmetros de uma linha conforme descritos no <a href="/documentacao-api/documentos/apendice#linha-do-documento">Apêndice</a></p></td></tr><tr><td>total_round_amount</td><td>float</td><td><p>Valor de Acerto</p><p></p><p>Poderá tomar valores no intervalo de -9.99 a 9.99.<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Os acertos estão disponíveis apenas em Documentos de Compra</p></td></tr><tr><td>payments</td><td>array</td><td><p>Pagamentos do Documento</p><p></p><p>Deverá conter uma lista de objetos, sendo que cada objeto poderá conter os parâmetros de um pagamento conforme descritos no <a href="/documentacao-api/documentos/apendice#pagamento-do-documento">Apêndice</a></p></td></tr><tr><td>finalize</td><td>boolean<br><sub><mark style="color:$info;">Default: false</mark></sub></td><td><p>Finalizar após criação</p><p></p><p>Se pretender finalizar de imediato um documento de pagamento imediato (ex: Factura-Recibo), deverá fornecer dados relativos ao(s) pagamento(s) no campo <code>payments</code>.</p></td></tr><tr><td>is_transport_document</td><td>boolean</td><td><p>Indica se  é Documento de Transporte</p><p></p><p>Consulte os parâmetros disponíveis para transporte no <a href="/documentacao-api/documentos/apendice#dados-para-transporte">Apêndice</a>.</p></td></tr><tr><td>force_communication</td><td>boolean</td><td><p>Força comunicação do documento à AT.</p><p>Caso não indique, o documento será comunicado em automático se assim for necessário.</p></td></tr><tr><td>generate_mb_reference</td><td>boolean</td><td><p>Gerar Referência Multibanco<br></p><p>Esta opção apenas será considerada caso esteja configurada para a sua empresa.</p></td></tr><tr><td>header_text</td><td>string</td><td>Informação no Cabeçalho do Documento</td></tr><tr><td>footer_text</td><td>string</td><td>Informação no Rodapé do Documento</td></tr><tr><td>print</td><td>boolean</td><td><p>Imprimir Documento após Criação</p><p></p><p>O ficheiro PDF do Documento é gerado ao finalizar.</p><p></p><p><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> O Documento deverá ser finalizado.</p><p></p><p>Consulte os parâmetros disponíveis para impressão no <a href="/documentacao-api/documentos/apendice#impressao-do-documento">Apêndice</a>.</p></td></tr><tr><td>email</td><td>boolean</td><td><p>Enviar por E-mail após Criação</p><p></p><p><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> O Documento deverá estar finalizado.</p><p></p><p>Consulte os parâmetros disponíveis para impressão no <a href="/documentacao-api/documentos/apendice#envio-por-e-mail-do-documento">Apêndice</a>.</p></td></tr></tbody></table>

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/documents/new/
    -d '{
        "document_nature_id": "302",
        "party_id": "1",
        "details": [
            {
                "code": "PROD1",
                "base_qty": 1
            },
            {
                "code": "PROD2",
                "base_qty": 2,
                "line_unit_value": 2.00
            }
        ],
        "payments": [
            {
                "payment_method_id": 1
            }
        ],
        "finalize": true
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "doc_key": "FSI A01/1",
    "document_date": "2023-01-11",
    "document_time": "13:32:36",
    "document_number": 1,
    "document_reference": "",
    "our_reference": "",
    "module_origin": 1,
    "party_id": 1,
    "party": {
        "class": 1601,
        "code": 1,
        "name": "Consumidor Final",
        "commercial_name": "",
        "fiscal_number": "999999990",
        "street1": "",
        "street2": "",
        "zip_code": "",
        "zip_locale": ""
    },
    "line_details_count": 2,
    "lines_total_quantity": 3.0,
    "is_valued": true,
    "is_tax_included": true,
    "total_gross_amount": 5.23,
    "global_discount1": 0.0,
    "total_global_discount": 0.0,
    "total_line_discount": 0.0,
    "total_net_amount": 4.2520325203,
    "total_taxes_amount": 0.9779674797,
    "total_amount": 5.23,
    "total_document_amount": 5.23,
    "total_round_amount": 0.0,
    "total_due_amount": 0.0,
    "due_date": "2023-01-11",
    "is_converted": false,
    "header_text": "",
    "footer_text": "",
    "number_of_prints": 0,
    "is_transport_document": false,
    "obs": "",
    "document_nature_id": 302,
    "document_nature": {
        "code": "FS", 
        "description": "Factura Simplificada"
    },
    "document_id": 2,
    "document": {
        "code": "FSI", 
        "document_name": "Factura Simplificada", 
        "ask_payment_onclose": true
    },
    "document_serie_id": 1,
    "document_serie": {
        "code": "A01", 
        "description": "Série A01"
    },
    "document_status_id": 1202,
    "document_status": {
        "code": "F",
        "description": "Finalizado"
    },
    "at_report_status_id": 1181,
    "at_report_status": {
        "code": "I",
        "description": "Isento"
    },
    "warehouse_id": 1,
    "warehouse": {
        "code": 1, 
        "description": "Armazém 1"
    },
    "salesman_id": 1,
    "salesman": {
        "code": 1, 
        "salesman_name": "Empregado 1"
    },
    "payment_term_id": 1,
    "payment_term": {
        "code": 1,
        "description": "Pronto Pagamento"
    },
    "payment_method_id": 1,
    "payment_method": {
        "code": 1,
        "description": "Dinheiro"
    },
    "origin_document_header_id": null,
    "origin_document_header": null
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Get

Obtém detalhes do documento.

## Obter Documento

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/documents/:id/`

#### Path Parameters

| Name | Type    | Description     |
| ---- | ------- | --------------- |
| id   | integer | ID do Documento |

#### Query Parameters

| Name     | Type    | Description                                                                                       |
| -------- | ------- | ------------------------------------------------------------------------------------------------- |
| extended | boolean | Inclui mais informação na resposta, incluindo listas de linhas, pagamentos e taxas  do documento. |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/documents/1/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "doc_key": "FSI A01/1",
    "document_date": "2023-01-10",
    "document_time": "11:30:48",
    "document_number": 1,
    "document_reference": "",
    "our_reference": "",
    "module_origin": 2,
    "party_id": 1,
    "party": {
        "class": 1601,
        "code": 1,
        "name": "Consumidor Final",
        "commercial_name": "",
        "fiscal_number": "999999990",
        "street1": "",
        "street2": "",
        "zip_code": "",
        "zip_locale": ""
    },
    "line_details_count": 5,
    "lines_total_quantity": 9.0,
    "is_valued": true,
    "is_tax_included": true,
    "total_gross_amount": 54.9,
    "global_discount1": 0.0,
    "total_global_discount": 0.0,
    "total_line_discount": 0.0,
    "total_net_amount": 44.6341463414,
    "total_taxes_amount": 10.2658536586,
    "total_amount": 54.9,
    "total_document_amount": 54.9,
    "total_round_amount": 0.0,
    "total_due_amount": 0.0,
    "due_date": "2023-01-10",
    "is_converted": false,
    "header_text": "",
    "footer_text": "",
    "number_of_prints": 0,
    "is_transport_document": false,
    "obs": "",
    "document_nature_id": 302,
    "document_nature": {
        "code": "FS",
        "description": "Factura Simplificada"
    },
    "document_id": 2,
    "document": {
        "code": "FSI",
        "document_name": "Factura Simplificada",
        "ask_payment_onclose": true
    },
    "document_serie_id": 1,
    "document_serie": {
        "code": "A01",
        "description": "Série A01"
    },
    "document_status_id": 1202,
    "document_status": {
        "code": "F",
        "description": "Finalizado"
    },
    "at_report_status_id": 1181,
    "at_report_status": {
        "code": "I",
        "description": "Isento"
    },
    "warehouse_id": 1,
    "warehouse": {
        "code": 1,
        "description": "Armazém 1"
    },
    "salesman_id": 1,
    "salesman": {
        "code": 1,
        "salesman_name": "Empregado 1"
    },
    "payment_term_id": 1,
    "payment_term": {
        "code": 1,
        "description": "Pronto Pagamento"
    },
    "payment_method_id": 1,
    "payment_method": {
        "code": 1,
        "description": "Dinheiro"
    },
    "origin_document_header_id": null,
    "origin_document_header": null
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Finalize

Finaliza documento com possibilidade de impressão ou envio de e-mail.

## Finalizar Documento

{% hint style="warning" %}
Documentos assinados (ex: Facturas) após a finalização passam a ter valor legal.\
Após a finalização, esta não poderá ser revertida e o conteúdo do documento não poderá mais ser alterado.&#x20;

A única ação passível de ser aplicada a documentos finalizados capaz de os afectar é a Anulação.
{% endhint %}

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/documents/:id/finalize/`

#### Path Parameters

| Name | Type    | Description     |
| ---- | ------- | --------------- |
| id   | integer | ID do Documento |

#### Request Body

| Name                    | Type    | Description                                                                                                                                                                                                                                                    |
| ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| payments                | Array   | <p>Pagamentos do Documento</p><p></p><p>Deverá conter uma lista de objetos, sendo que cada objeto poderá conter os parâmetros de um pagamento conforme descritos no <a href="/documentacao-api/documentos/apendice#pagamento-do-documento">Apêndice</a>.</p>   |
| print                   | boolean | <p>Imprimir Documento após a Finalização</p><p> </p><p>O ficheiro PDF do Documento é gerado ao finalizar.<br><br>Consulte os parâmetros disponíveis para impressão no <a href="/documentacao-api/documentos/apendice#impressao-do-documento">Apêndice</a>.</p> |
| email                   | boolean | <p>Enviar por E-mail após a Finalização<br><br>Consulte os parâmetros disponíveis para impressão no <a href="/documentacao-api/documentos/apendice#envio-por-e-mail-do-documento">Apêndice</a>.</p>                                                            |
| generate\_mb\_reference | boolean | <p>Gerar Referência de Multibanco</p><p></p><p>Esta opção apenas será considerada caso esteja configurada para a sua empresa.</p>                                                                                                                              |
| force\_communication    | boolean | <p>Força comunicação do documento à AT</p><p></p><p>Caso não indique, o documento será comunicado em automático se assim for necessário.</p>                                                                                                                   |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/documents/1/finalize/
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

<pre class="language-json"><code class="lang-json">{
    "id": 7641,
    "doc_key": "FSI A01/1",
    "document_date": "2023-01-11",
    "document_time": "13:32:36",
    "document_number": 1,
    "document_reference": "",
    "our_reference": "",
    "module_origin": 1,
    "party_id": 1,
    "party": {
        "class": 1601,
        "code": 1,
        "name": "Consumidor Final",
        "commercial_name": "",
        "fiscal_number": "999999990",
        "street1": "",
        "street2": "",
        "zip_code": "",
        "zip_locale": ""
    },
    "line_details_count": 2,
    "lines_total_quantity": 3.0,
    "is_valued": true,
    "is_tax_included": true,
    "total_gross_amount": 5.23,
    "global_discount1": 0.0,
    "total_global_discount": 0.0,
    "total_line_discount": 0.0,
    "total_net_amount": 4.2520325203,
    "total_taxes_amount": 0.9779674797,
    "total_amount": 5.23,
    "total_document_amount": 5.23,
    "total_round_amount": 0.0,
    "total_due_amount": 0.0,
    "due_date": "2023-01-11",
    "is_converted": false,
    "header_text": "",
    "footer_text": "",
    "number_of_prints": 0,
    "is_transport_document": false,
    "obs": "",
    "document_nature_id": 302,
    "document_nature": {
        "code": "FS", 
        "description": "Factura Simplificada"
    },
    "document_id": 2,
    "document": {
        "code": "FSI", 
        "document_name": "Factura Simplificada", 
        "ask_payment_onclose": true
    },
    "document_serie_id": 1,
    "document_serie": {
        "code": "A01", 
        "description": "Série A01"
    },
<strong>    "document_status_id": 1202,
</strong><strong>    "document_status": {
</strong><strong>        "code": "F",
</strong><strong>        "description": "Finalizado"
</strong><strong>    },
</strong>    "at_report_status_id": 1181,
    "at_report_status": {
        "code": "I",
        "description": "Isento"
    },
    "warehouse_id": 1,
    "warehouse": {
        "code": 1, 
        "description": "Armazém 1"
    },
    "salesman_id": 1,
    "salesman": {
        "code": 1, 
        "salesman_name": "Empregado 1"
    },
    "payment_term_id": 1,
    "payment_term": {
        "code": 1,
        "description": "Pronto Pagamento"
    },
    "payment_method_id": 1,
    "payment_method": {
        "code": 1,
        "description": "Dinheiro"
    },
    "origin_document_header_id": null,
    "origin_document_header": null
}
</code></pre>

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Delete

Apaga um documento em preparação.

## Apagar Documento

{% hint style="warning" %}
Atenção! Esta ação apenas pode ser executada em documentos ainda em preparação.
{% endhint %}

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/documents/:id/delete/`

#### Path Parameters

| Name                                 | Type    | Description                             |
| ------------------------------------ | ------- | --------------------------------------- |
| id<mark style="color:red;">\*</mark> | integer | O ID do documento que pretende eliminar |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/documents/1/delete/
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Linhas


# List

Fornece uma lista das linhas do documento.

## Listar Linhas do Documento

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/documents/:doc_id/details/`

#### Path Parameters

| Name    | Type    | Description     |
| ------- | ------- | --------------- |
| doc\_id | integer | ID do Documento |

#### Query Parameters

| Name   | Type    | Description                                                                                                                                        |
| ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| limit  | integer | Define o número de registos por pesquisa.                                                                                                          |
| offset | integer | <p>Indica a posição inicial da pesquisa.</p><p>Retorna a lista de registos compreendida entre <code>offset</code> e <code>offset+limit</code>.</p> |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/documents/1/details/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "limit": 10,
    "offset": 0,
    "count": 2,
    "next": null,
    "previous": null,
    "results":[
        {
            "id": 1,
            "line_number": 1,
            "line_subitem": 0,
            "code": "001",
            "description": "Produto 1",
            "short_description": "Produto 1",
            "has_lots": false,
            "use_serial_number": false,
            "base_qty": 2.0,
            "global_discount1": 0.0,
            "line_discount1": 0.0,
            "line_discount2": 0.0,
            "line_discount3": 0.0,
            "total_gross_amount": 50.0,
            "total_discount_amount": 0.0,
            "total_net_amount": 47.1698113208,
            "total_taxes_amount": 2.8301886792,
            "line_unit_value": 25.0,
            "line_total_value": 50.0,
            "use_sizes_colors": false,
            "base_measure_unit_id": 1,
            "base_measure_unit":{"code": "UNI", "description": "Unidade"},
            "vat_tax_id": 3,
            "vat_tax":{"description": "Taxa Reduzida", "tax_rate": 6.0}
        },
        {
            "id": 2,
            "line_number": 2,
            "line_subitem": 0,
            "code": "002",
            "description": "Produto 2",
            "short_description": "Produto 2",
            "has_lots": false,
            "use_serial_number": false,
            "base_qty": 1.0,
            "global_discount1": 0.0,
            "line_discount1": 0.0,
            "line_discount2": 0.0,
            "line_discount3": 0.0,
            "total_gross_amount": 2.0,
            "total_discount_amount": 0.0,
            "total_net_amount": 1.8867924528,
            "total_taxes_amount": 0.1132075472,
            "line_unit_value": 2.0,
            "line_total_value": 2.0,
            "use_sizes_colors": false,
            "base_measure_unit_id": 18,
            "base_measure_unit":{"code": "ML", "description": "Mililitro"},
            "vat_tax_id": 3,
            "vat_tax":{"description": "Taxa Reduzida", "tax_rate": 6.0}
        }
    ]
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)

{% hint style="info" %}
**Notas:** Alguns dos campos do termo de pesquisa geral poderão ser incluídos mediante critérios específicos (Ex: Descrição será incluída na pesquisa geral apenas se o termo de pesquisa contiver 3 ou mais caracteres). Por defeito, o comportamento expectável será obter-se todos os items cujo o texto a pesquisar (search) esteja CONTIDO em pelo menos um dos campos incluídos na pesquisa geral.
{% endhint %}


# Create

Cria uma linha no documento.

## Criar Linha de Documento

{% hint style="warning" %}
Atenção! Esta ação apenas pode ser executada nos documentos em preparação.
{% endhint %}

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/document/:doc_id/details/new/`

#### Path Parameters

| Name    | Type    | Description     |
| ------- | ------- | --------------- |
| doc\_id | integer | ID do Documento |

#### Request Body

<table data-search="false"><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>line_number</td><td>integer</td><td>Número da Linha Principal<br><br>Usado para a criação de sub-linhas, em casos em que tal é permitido (ex: produtos compostos)<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Não surte efeito se não existir já uma linha com o número fornecido.</td></tr><tr><td>code<mark style="color:red;">*</mark></td><td>string</td><td>Código do Produto<br><br>Pode referir-se tanto ao 'código' como ao 'código de barras' de um produto, ou ainda a um 'código alternativo' por este usado.</td></tr><tr><td>description</td><td>string</td><td>Descrição<br><br>Este valor, se preenchido, vai sobrepor-se à descrição na ficha do produto apenas na presente linha.</td></tr><tr><td>short_description</td><td>string</td><td>Descrição Curta<br><br>Este valor, se preenchido, vai sobrepor-se à descrição curta na ficha do produto apenas na presente linha.</td></tr><tr><td>long_description</td><td>string</td><td>Descrição Alargada<br><br>Este valor, se preenchido, vai sobrepor-se à descrição alargada na ficha do produto apenas na presente linha.<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo está dependente da configuração <code>use_long_description</code></td></tr><tr><td>base_qty</td><td>float<br><sub><mark style="color:$info;">Default: 1</mark></sub></td><td>Quantidade</td></tr><tr><td>line_unit_value</td><td>float</td><td>Preço Unitário<br><br>O valor fornecido deverá ser o Preço Unitário sem IVA se o documento estiver definido como contendo valores sem IVA. Deverá já incluir IVA caso contrário.</td></tr><tr><td>line_discount1</td><td>float</td><td>Desconto de Linha #1</td></tr><tr><td>line_discount2</td><td>float</td><td>Desconto de Linha #2</td></tr><tr><td>lot_number</td><td>string</td><td>Número do Lote<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo é condicionada pela utilização de lotes no produto e no tipo de documento usados. </td></tr><tr><td>serial_number</td><td>array</td><td>Números de Série<br><br>Lista de IDs dos números de série a usar na linha<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo é condicionada pela utilização de números de série no produto e no tipo de documento usados. </td></tr><tr><td>size_id</td><td>integer</td><td>Tamanho<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo é condicionada pela utilização de cores e tamanhos no produto e no tipo de documento usados.</td></tr><tr><td>color_id</td><td>integer</td><td>Cor<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo é condicionada pela utilização de cores e tamanhos no produto e no tipo de documento usados.</td></tr><tr><td>vat_tax_id</td><td>integer</td><td><p>Taxa de IVA</p><p><br>Consulte a tabela <a href="/documentacao-api/taxas/list#lista-de-tabelas-de-impostos">Tabelas de Impostos</a>.<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo está dependente da configuração <code>allow_tax_code_change_documents</code></p></td></tr></tbody></table>

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/documents/1/details/new/
    -d '{
        "code": "001",
        "base_qty": 2.0,
        "line_unit_value": 25.0
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "line_number": 1,
    "line_subitem": 0,
    "document_header_id": 1,
    "document_header": {
        "doc_key": "FSI A01/1",
        "document_name": "Factura Simplificada"
    },
    "code": "001",
    "product_id": 1,
    "description": "Produto 1",
    "short_description": "Produto 1",
    "has_lots": false,
    "use_serial_number": false,
    "use_sizes_colors": false,
    "base_qty": 2.0,
    "base_measure_unit_id": 1,
    "base_measure_unit":{
        "code": "UNI",
        "description": "Unidade"
    },
    "quantity": 1.0,
    "measure_unit_id": 1,
    "measure_unit": {
        "code": "UNI",
        "description": "Unidade"
    },
    "line_unit_value": 25.0,
    "global_discount1": 0.0,
    "line_discount1": 0.0,
    "line_discount2": 0.0,
    "line_discount3": 0.0,
    "vat_tax_id": 3,
    "vat_tax": {
        "description": "Taxa Reduzida",
        "tax_rate": 6.0
    },
    "tax_exemption_id": null,
    "tax_exemption": null,
    "total_gross_amount": 50.0,
    "total_discount_amount": 0.0,
    "total_net_amount": 47.1698113208,
    "total_taxes_amount": 2.8301886792,
    "line_total_value": 50.0
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Get

Obtém detalhes da linha do documento.

## Obter Linha do Documento

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/documents/:doc_id/details/:id/`

#### Path Parameters

| Name    | Type    | Description              |
| ------- | ------- | ------------------------ |
| doc\_id | integer | ID do Documento          |
| id      | integer | ID da Linha do Documento |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/documents/1/details/1/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "line_number": 1,
    "line_subitem": 0,
    "document_header_id": 1,
    "document_header": {
        "doc_key": "FSI A01/1",
        "document_name": "Factura Simplificada"
    },
    "code": "001",
    "product_id": 1,
    "description": "Produto 1",
    "short_description": "Produto 1",
    "has_lots": false,
    "use_serial_number": false,
    "use_sizes_colors": false,
    "base_qty": 2.0,
    "base_measure_unit_id": 1,
    "base_measure_unit":{
        "code": "UNI",
        "description": "Unidade"
    },
    "quantity": 1.0,
    "measure_unit_id": 1,
    "measure_unit": {
        "code": "UNI",
        "description": "Unidade"
    },
    "line_unit_value": 25.0,
    "global_discount1": 0.0,
    "line_discount1": 0.0,
    "line_discount2": 0.0,
    "line_discount3": 0.0,
    "vat_tax_id": 3,
    "vat_tax": {
        "description": "Taxa Reduzida",
        "tax_rate": 6.0
    },
    "tax_exemption_id": null,
    "tax_exemption": null,
    "total_gross_amount": 50.0,
    "total_discount_amount": 0.0,
    "total_net_amount": 47.1698113208,
    "total_taxes_amount": 2.8301886792,
    "line_total_value": 50.0
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Update

Altera valores de uma linha do documento.

## Alterar Linha de Documento

{% hint style="warning" %}
Atenção! Esta ação apenas pode ser executada em documentos ainda em preparação.
{% endhint %}

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/documents/:doc_id/details/:id/update/`

#### Path Parameters

| Name    | Type    | Description              |
| ------- | ------- | ------------------------ |
| doc\_id | integer | ID do Documento          |
| id      | integer | ID da Linha do Documento |

#### Request Body

<table data-search="false"><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>description</td><td>string</td><td>Descrição</td></tr><tr><td>short_description</td><td>string</td><td>Descrição Curta</td></tr><tr><td>long_description</td><td>string</td><td>Descrição Alargada<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo está dependente da configuração <code>use_long_description</code></td></tr><tr><td>base_qty</td><td>float<br><sub><mark style="color:$info;">Default: 1</mark></sub></td><td>Quantidade</td></tr><tr><td>line_unit_value</td><td>float</td><td>Preço Unitário<br><br>O valor fornecido deverá ser o Preço Unitário sem IVA se o documento estiver definido como contendo valores sem IVA. Deverá já incluir IVA caso contrário.</td></tr><tr><td>line_discount1</td><td>float</td><td>Desconto de Linha #1</td></tr><tr><td>line_discount2</td><td>float</td><td>Desconto de Linha #2</td></tr><tr><td>lot_number</td><td>string</td><td>Número do Lote<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo é condicionada pela utilização de lotes no produto e no tipo de documento usados. </td></tr><tr><td>serial_number</td><td>array</td><td>Números de Série<br><br>Lista de IDs dos números de série a usar na linha<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo é condicionada pela utilização de números de série no produto e no tipo de documento usados. </td></tr><tr><td>size_id</td><td>integer</td><td>Tamanho<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo é condicionada pela utilização de cores e tamanhos no produto e no tipo de documento usados.</td></tr><tr><td>color_id</td><td>integer</td><td>Cor<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo é condicionada pela utilização de cores e tamanhos no produto e no tipo de documento usados.</td></tr><tr><td>vat_tax_id</td><td>integer</td><td><p>Taxa de IVA</p><p><br>Consulte a tabela <a href="/documentacao-api/taxas/list#lista-de-tabelas-de-impostos">Tabelas de Impostos</a>.<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo está dependente da configuração <code>allow_tax_code_change_documents</code></p></td></tr></tbody></table>

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/documents/1/details/1/update/
    -d '{
        "description": "Descrição Personalizada"
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

<pre class="language-json"><code class="lang-json">{
    "id": 1,
    "line_number": 1,
    "line_subitem": 0,
    "document_header_id": 1,
    "document_header": {
        "doc_key": "FSI A01/1",
        "document_name": "Factura Simplificada"
    },
    "code": "001",
    "product_id": 1,
<strong>    "description": "Descrição Personalizada",
</strong>    "short_description": "Produto 1",
    "has_lots": false,
    "use_serial_number": false,
    "use_sizes_colors": false,
    "base_qty": 2.0,
    "base_measure_unit_id": 1,
    "base_measure_unit":{
        "code": "UNI",
        "description": "Unidade"
    },
    "quantity": 1.0,
    "measure_unit_id": 1,
    "measure_unit": {
        "code": "UNI",
        "description": "Unidade"
    },
    "line_unit_value": 25.0,
    "global_discount1": 0.0,
    "line_discount1": 0.0,
    "line_discount2": 0.0,
    "line_discount3": 0.0,
    "vat_tax_id": 3,
    "vat_tax": {
        "description": "Taxa Reduzida",
        "tax_rate": 6.0
    },
    "tax_exemption_id": null,
    "tax_exemption": null,
    "total_gross_amount": 50.0,
    "total_discount_amount": 0.0,
    "total_net_amount": 47.1698113208,
    "total_taxes_amount": 2.8301886792,
    "line_total_value": 50.0
}
</code></pre>

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Delete

Apaga a linha de um documento.

## Apagar Linha de Documento

{% hint style="warning" %}
Atenção! Esta ação apenas pode ser executada em documentos ainda em preparação.
{% endhint %}

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/documents/:doc_id/details/:id/delete/`

#### Path Parameters

| Name    | Type    | Description              |
| ------- | ------- | ------------------------ |
| doc\_id | integer | ID do Documento          |
| id      | integer | ID da Linha do Documento |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/documents/1/details/1/delete/
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Pagamentos


# List

Fornece uma lista dos pagamentos do documento.

## Listar Pagamentos do Documento

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/documents/:id/payments/`

#### Query Parameters

| Name   | Type    | Description                                                                                                                                        |
| ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| limit  | integer | Define o número de registos por pesquisa.                                                                                                          |
| offset | integer | <p>Indica a posição inicial da pesquisa.</p><p>Retorna a lista de registos compreendida entre <code>offset</code> e <code>offset+limit</code>.</p> |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/documents/1/payments/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "limit": 10,
    "offset": 0,
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "payment_date": "2023-01-16T12:40:46.841928Z",
            "total_payment": 52.0,
            "payment_method_id": 1,
            "payment_method":{"code": 1, "description": "Dinheiro"}
        }
    ]
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)

{% hint style="info" %}
**Notas:** Alguns dos campos do termo de pesquisa geral poderão ser incluídos mediante critérios específicos (Ex: Descrição será incluída na pesquisa geral apenas se o termo de pesquisa contiver 3 ou mais caracteres). Por defeito, o comportamento expectável será obter-se todos os items cujo o texto a pesquisar (search) esteja CONTIDO em pelo menos um dos campos incluídos na pesquisa geral.
{% endhint %}


# Ações


# Emitir Nota de Crédito

Emite uma nota de crédito, com origem no documento de venda com o ID fornecido.

## Emitir Nota de Crédito

{% hint style="danger" %}
**Este endpoint deverá ser usado apenas para emissão de Notas de Crédito de Venda.**

As Notas de Crédito a Fornecedor, não tendo a necessidade de fazer referência a um documento de origem, deverão ser criadas recorrendo ao habitual endpoint [Create](/documentacao-api/documentos/create).
{% endhint %}

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/documents/:id/emit_credit_note/`

#### Path Parameters

| Name                                 | Type    | Description               |
| ------------------------------------ | ------- | ------------------------- |
| id<mark style="color:red;">\*</mark> | integer | ID do Documento de Origem |

#### Request Body

| Name                                               | Type    | Description                                                                                                                                                                                                                                                                         |
| -------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| details<mark style="color:red;">\*</mark>          | array   | <p>Linhas do Documento de Origem.</p><p></p><p>Poderá conter uma lista de objectos, sendo que cada objecto deverá conter os parâmetros de uma Linha de Origem conforme descritos no <a href="/documentacao-api/documentos/apendice#linhas-do-documento-de-origem">Apêndice</a>.</p> |
| print                                              | boolean | <p>Imprimir Documento após emissão. </p><p>Apenas pode imprimir documentos finalizados.</p><p></p><p>Consulte os parâmetros disponíveis para impressão no <a href="/documentacao-api/documentos/apendice#impressao-do-documento">Apêndice</a>.</p>                                  |
| email                                              | boolean | <p>Enviar por E-mail após a emissão.</p><p>Apenas pode enviar por e-mail documentos finalizados.</p><p></p><p>Consulte os parâmetros disponíveis para impressão no <a href="/documentacao-api/documentos/apendice#envio-por-e-mail-do-documento">Apêndice</a>.</p>                  |
| emission\_reason<mark style="color:red;">\*</mark> | string  | Motivo de Emissão.                                                                                                                                                                                                                                                                  |
| force\_communication                               | boolean | <p>Força comunicação do documento à AT.</p><p>Caso não indique, o documento será comunicado em automático se assim for necessário.</p>                                                                                                                                              |
| payment\_method\_id                                | integer | <p>Método de Pagamento.</p><p></p><p>Poderá ser necessário definir um Método de Pagamento no caso de se tratar de uma Nota de Crédito de devolução.</p>                                                                                                                             |
| finalize                                           | boolean | Finalizar o Documento após a emissão.                                                                                                                                                                                                                                               |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/documents/1470/emit_credit_note/
    -d '{
        "emission_reason": "Devolução",
        "details": [
            {
                "id": 1122,
                "base_qty": 1
            },
            {
                "id": 1123
            }
        ],
        "finalize": true
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
  "id": 1,
  "doc_key": "NCR A01/1",
  "document_date": "2023-08-01",
  "document_time": "15:50:29",
  "document_number": 4,
  "document_reference": "",
  "our_reference": "",
  "module_origin": 1,
  "party_id": 2,
  "party": {
    "class": 1601,
    "code": 2,
    "name": "Cliente Demo",
    "commercial_name": "",
    "fiscal_number": "123456789",
    "street1": "Desconhecido",
    "street2": "",
    "zip_code": "0000-000",
    "zip_locale": "Desconhecido"
  },
  "line_details_count": 2,
  "lines_total_quantity": 2.0,
  "is_valued": true,
  "is_tax_included": false,
  "total_gross_amount": 6.07,
  "global_discount1": 0.0,
  "total_global_discount": 0.0,
  "total_line_discount": 0.0,
  "total_net_amount": 6.07,
  "total_taxes_amount": 0.9361,
  "total_amount": 7.01,
  "total_document_amount": 7.01,
  "total_round_amount": 0.0,
  "total_due_amount": 7.01,
  "due_date": "2023-08-01",
  "is_converted": false,
  "header_text": "",
  "footer_text": "",
  "number_of_prints": 0,
  "is_transport_document": false,
  "obs": "",
  "has_withholding": false,
  "document_nature_id": 305,
  "document_nature": {
    "code": "NC",
    "description": "Nota de Crédito"
  },
  "document_id": 5,
  "document": {
    "code": "NCR",
    "document_name": "Nota de Crédito",
    "ask_payment_onclose": false
  },
  "document_serie_id": 1,
  "document_serie": {
    "code": "A01",
    "description": "Série A01"
  },
  "document_status_id": 1202,
  "document_status": {
    "code": "F",
    "description": "Finalizado"
  },
  "warehouse_id": 1,
  "warehouse": {
    "code": 1,
    "description": "Armazém 1"
  },
  "salesman_id": 2,
  "salesman": {
    "code": 2,
    "salesman_name": "Vendedor 2"
  },
  "payment_term_id": 1,
  "payment_term": {
    "code": 1,
    "description": "Pronto Pagamento"
  },
  "payment_method_id": null,
  "payment_method": null,
  "origin_document_header_id": 1470,
  "origin_document_header": {
    "doc_key": "FAC A01/1",
    "document_name": "Factura"
  }
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Print

Gera ficheiro PDF do documento para impressão.

## Imprimir Documento

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/documents/:id/print/`

#### Path Parameters

| Name                                 | Type    | Description     |
| ------------------------------------ | ------- | --------------- |
| id<mark style="color:red;">\*</mark> | integer | ID do Documento |

#### Request Body

| Name  | Type    | Description                                                                                                                                                                                                                                                                                                |
| ----- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| print | boolean | <p>Imprimir Documento</p><p></p><p><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> O Documento deverá estar finalizado.</p><p></p><p>Consulte os parâmetros disponíveis para impressão no <a href="/documentacao-api/documentos/apendice#impressao-do-documento">Apêndice</a>.</p> |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/documents/1/print/
    -d '{
        "print": true,
        "print_copy": 3
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "doc_key": "FSI A01/1",
    "print": {
        "filename": "FS__FSI_A01_1__2023_01_11_1673450093.pdf",
        "url": "https://app.cloudinvoice/downloads/xxxxxxxxxx-xxxx-xxx-xxxx-xxxxxxxxx/"
    }
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Email

Envia documento finalizado/anulado por E-mail.

## Enviar Documento por E-mail

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/documents/:id/email/`

#### Path Parameters

| Name                                 | Type    | Description     |
| ------------------------------------ | ------- | --------------- |
| id<mark style="color:red;">\*</mark> | integer | ID do Documento |

#### Request Body

| Name  | Type    | Description                                                                                                                                                                                                                                                                                                      |
| ----- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| email | boolean | <p>Enviar por E-mail</p><p></p><p><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> O Documento deverá estar finalizado.</p><p></p><p>Consulte os parâmetros disponíveis para impressão no <a href="/documentacao-api/documentos/apendice#envio-por-e-mail-do-documento">Apêndice</a>.</p> |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/documents/1/email/
    -d '{
        "email": true,
        "email_address": "email@address.com"
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "doc_key": "FSI A01/1",
    "print": {
        "filename": "FS__FSI_A01_1__2023_01_11_1673450093.pdf",
        "url": "https://app.cloudinvoice/downloads/xxxxxxxxxx-xxxx-xxx-xxxx-xxxxxxxxx/"
    }
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Annul

Anula documento finalizado.

## Anular Documento

{% hint style="danger" %}
A anulação de um documento não poderá ser revertida em circunstância alguma.
{% endhint %}

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/documents/:id/annul/`

#### Path Parameters

| Name                                 | Type    | Description     |
| ------------------------------------ | ------- | --------------- |
| id<mark style="color:red;">\*</mark> | integer | ID do Documento |

#### Request Body

| Name                                             | Type    | Description                                                                                                                                                                                            |
| ------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| status\_reason<mark style="color:red;">\*</mark> | string  | Motivo da Anulação                                                                                                                                                                                     |
| print                                            | boolean | <p>Imprimir Documento após a Anulação </p><p></p><p>Consulte os parâmetros disponíveis para impressão no <a href="/documentacao-api/documentos/apendice#impressao-do-documento">Apêndice</a>.</p>      |
| email                                            | boolean | <p>Enviar por E-mail após a Anulação</p><p></p><p>Consulte os parâmetros disponíveis para impressão no <a href="/documentacao-api/documentos/apendice#envio-por-e-mail-do-documento">Apêndice</a>.</p> |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/documents/1/annul/
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

<pre class="language-json"><code class="lang-json">{
    "id": 1,
    "doc_key": "FSI A01/1",
    "document_date": "2023-01-11",
    "document_time": "13:32:36",
    "document_number": 1,
    "document_reference": "",
    "our_reference": "",
    "module_origin": 1,
    "party_id": 1,
    "party": {
        "class": 1601,
        "code": 1,
        "name": "Consumidor Final",
        "commercial_name": "",
        "fiscal_number": "999999990",
        "street1": "",
        "street2": "",
        "zip_code": "",
        "zip_locale": ""
    },
    "line_details_count": 2,
    "lines_total_quantity": 3.0,
    "is_valued": true,
    "is_tax_included": true,
    "total_gross_amount": 5.23,
    "global_discount1": 0.0,
    "total_global_discount": 0.0,
    "total_line_discount": 0.0,
    "total_net_amount": 4.2520325203,
    "total_taxes_amount": 0.9779674797,
    "total_amount": 5.23,
    "total_document_amount": 5.23,
    "total_round_amount": 0.0,
    "total_due_amount": 0.0,
    "due_date": "2023-01-11",
    "is_converted": false,
    "header_text": "",
    "footer_text": "",
    "number_of_prints": 0,
    "is_transport_document": false,
    "obs": "",
    "document_nature_id": 302,
    "document_nature": {
        "code": "FS", 
        "description": "Factura Simplificada"
    },
    "document_id": 2,
    "document": {
        "code": "FSI", 
        "document_name": "Factura Simplificada", 
        "ask_payment_onclose": true
    },
    "document_serie_id": 1,
    "document_serie": {
        "code": "A01", 
        "description": "Série A01"
    },
<strong>    "document_status_id": 1203,
</strong><strong>    "document_status": {
</strong><strong>        "code": "A",
</strong><strong>        "description": "Anulado"
</strong><strong>    },
</strong>    "warehouse_id": 1,
    "warehouse": {
        "code": 1, 
        "description": "Armazém 1"
    },
    "salesman_id": 1,
    "salesman": {
        "code": 1, 
        "salesman_name": "Empregado 1"
    },
    "payment_term_id": 1,
    "payment_term": {
        "code": 1,
        "description": "Pronto Pagamento"
    },
    "payment_method_id": 1,
    "payment_method": {
        "code": 1,
        "description": "Dinheiro"
    },
    "origin_document_header_id": null,
    "origin_document_header": null
}
</code></pre>

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Exportar

Exporta documentos para ficheiros, em diferentes formatos de dados.

## Exportar Documento

{% hint style="warning" %}
Ao contrário do habitual na API CloudInvoice, a resposta a este endpoint é dada em byte stream com Content-Type variável, consoante o tipo (MIME type) do ficheiro gerado (ex: XML → application/xml).

É também incluido no header Content-Disposition da resposta o nome sugerido para o ficheiro.
{% endhint %}

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/documents/:id/export/`

#### Path Parameters

| Name | Type    | Description     |
| ---- | ------- | --------------- |
| id   | integer | ID do Documento |

#### Query Params

<table data-search="false"><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>format<mark style="color:$danger;">*</mark></td><td>string</td><td><p>Formato do Ficheiro</p><p></p><p>Valores possíveis: <code>ubl</code></p></td></tr></tbody></table>

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X GET https://api.cloudinvoice.net/documents/1/export/
    -d 'format=ubl'
```

{% endtab %}

{% tab title="Ficheiro UBL (CIUS-PT)" %}

```xml
<?xml-model href="../schematron/urn_feap.gov.pt_CIUS-PT_1.0.5.sch" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron" phase="#ALL" title="Main schema"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2" xmlns:xades="http://uri.etsi.org/01903/v1.3.2#" xmlns:n1="http://uri.etsi.org/01903/v1.4.1#" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:ext="urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2" xmlns:n2="urn:oasis:names:specification:ubl:schema:xsd:CommonSignatureComponents-2" xmlns:qdt="urn:oasis:names:specification:ubl:schema:xsd:QualifiedDataTypes-2" xmlns:sac="urn:oasis:names:specification:ubl:schema:xsd:SignatureAggregateComponents-2" xmlns:sbc="urn:oasis:names:specification:ubl:schema:xsd:SignatureBasicComponents-2" xmlns:udt="urn:oasis:names:specification:ubl:schema:xsd:UnqualifiedDataTypes-2" xmlns:ccts-cct="urn:un:unece:uncefact:data:specification:CoreComponentTypeSchemaModule:2" xmlns:ccts="urn:un:unece:uncefact:documentation:2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:feap.gov.pt:CIUS-PT:2.1.2</cbc:CustomizationID>
	<cbc:ProfileID>urn:www:espap:pt:profiles:profile1:ver1.0</cbc:ProfileID>
	<cbc:ID>A01/1</cbc:ID>
	<cbc:IssueDate>2023-01-04</cbc:IssueDate>
	<cbc:DueDate>2023-01-04</cbc:DueDate>
	<cbc:InvoiceTypeCode listID="UNCL1001">FT</cbc:InvoiceTypeCode>
	<cbc:Note>#NUMBER@ATCERTIFIEDPROGRAM#2713#</cbc:Note>
	<cbc:Note>#HASHCODE@ATCERTIFIEDPROGRAM#g1d8#</cbc:Note>
	<cbc:Note>#DESCRIPTION@ATCERTIFIEDPROGRAM# - Processado por programa certificado n. 2713/AT#</cbc:Note>
	<cbc:DocumentCurrencyCode listID="ISO4217">EUR</cbc:DocumentCurrencyCode>
	<cac:AdditionalDocumentReference>
		<cbc:ID schemeID="ANG">MPVYXKPF-1-Nº sequêncial</cbc:ID>
		<cbc:DocumentTypeCode>130</cbc:DocumentTypeCode>
	</cac:AdditionalDocumentReference>
	<cac:AdditionalDocumentReference>
		<cbc:ID>A01/1</cbc:ID>
		<cbc:DocumentDescription>INVOICE_REPRESENTATION</cbc:DocumentDescription>
		<cac:Attachment>...</cac:Attachment>
	</cac:AdditionalDocumentReference>
	<cac:AccountingSupplierParty>
		<cac:Party>
			...
		</cac:Party>
	</cac:AccountingSupplierParty>
	<cac:AccountingCustomerParty>
		<cac:Party>
			...
		</cac:Party>
	</cac:AccountingCustomerParty>
	<cac:Delivery>
		<cac:DeliveryLocation>
			<cac:Address>
				<cbc:StreetName>Desconhecido</cbc:StreetName>
				<cbc:CityName>Desconhecido</cbc:CityName>
				<cbc:PostalZone>0000-000</cbc:PostalZone>
				<cac:Country>
					<cbc:IdentificationCode listID="ISO3166-1">PT</cbc:IdentificationCode>
				</cac:Country>
			</cac:Address>
		</cac:DeliveryLocation>
	</cac:Delivery>
	<cac:TaxTotal>
		<cbc:TaxAmount currencyID="EUR">23.00</cbc:TaxAmount>
		<cac:TaxSubtotal>
			<cbc:TaxableAmount currencyID="EUR">100.00</cbc:TaxableAmount>
			<cbc:TaxAmount currencyID="EUR">23.00</cbc:TaxAmount>
			<cac:TaxCategory>
				<cbc:ID schemeID="UN/ECE 5305">NOR</cbc:ID>
				<cbc:Percent>23.00</cbc:Percent>
				<cac:TaxScheme>
					<cbc:ID>VAT</cbc:ID>
				</cac:TaxScheme>
			</cac:TaxCategory>
		</cac:TaxSubtotal>
	</cac:TaxTotal>
	<cac:LegalMonetaryTotal>
		<cbc:LineExtensionAmount currencyID="EUR">100.00</cbc:LineExtensionAmount>
		<cbc:TaxExclusiveAmount currencyID="EUR">100.00</cbc:TaxExclusiveAmount>
		<cbc:TaxInclusiveAmount currencyID="EUR">123.00</cbc:TaxInclusiveAmount>
		<cbc:AllowanceTotalAmount currencyID="EUR">0.00</cbc:AllowanceTotalAmount>
		<cbc:PrepaidAmount currencyID="EUR">123.00</cbc:PrepaidAmount>
		<cbc:PayableAmount currencyID="EUR">0.00</cbc:PayableAmount>
	</cac:LegalMonetaryTotal>
	<cac:InvoiceLine>
		<cbc:ID>1</cbc:ID>
		<cbc:InvoicedQuantity unitCode="">1.000</cbc:InvoicedQuantity>
		<cbc:LineExtensionAmount currencyID="EUR">100.00</cbc:LineExtensionAmount>
		<cac:Item>
			<cbc:Name>Produto 1</cbc:Name>
			<cac:ClassifiedTaxCategory>
				<cbc:ID schemeID="UN/ECE 5305">NOR</cbc:ID>
				<cbc:Percent>23.00</cbc:Percent>
				<cac:TaxScheme>
					<cbc:ID>VAT</cbc:ID>
				</cac:TaxScheme>
			</cac:ClassifiedTaxCategory>
		</cac:Item>
		<cac:Price>
			<cbc:PriceAmount currencyID="EUR">100.00</cbc:PriceAmount>
			<cbc:BaseQuantity unitCode="">1.00</cbc:BaseQuantity>
		</cac:Price>
	</cac:InvoiceLine>
</Invoice>
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Comunicar à AT

Comunica o documento à Autoridade Tributária via WebServices.

## Comunicar Documento por Webservice

{% hint style="danger" %}
A utilização deste endpoint requer que tenha activada a comunicação de documentos por webservice e configuradas as credenciais de acesso ao serviço da Autoridade Tributária no seu BackOffice.
{% endhint %}

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/documents/:id/communicate/`

#### Path Parameters

| Name                                 | Type    | Description     |
| ------------------------------------ | ------- | --------------- |
| id<mark style="color:red;">\*</mark> | integer | ID do Documento |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/documents/7/communicate/
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

<pre class="language-json"><code class="lang-json">{
    "id": 7,
    "doc_key": "GTR A01/1",
    "document_nature_id": 322,
    "document_nature": {
        "code": "GT",
        "description": "Guia de Transporte"
    },
    "document_id": 9,
    "document": {
        "code": "GTR",
        "document_name": "Guia de Transporte",
        "ask_payment_onclose": false
    },
    "document_serie_id": 22,
    "document_serie": {
        "code": "A01",
        "description": "A01"
    },
    "document_status_id": 1202,
    "document_status": {
        "code": "F",
        "description": "Finalizado"
    },
<strong>    "at_report_status_id": 1182,
</strong><strong>    "at_report_status": {
</strong><strong>        "code": "C",
</strong><strong>        "description": "Comunicado"
</strong><strong>    },
</strong>    "document_date": "2026-08-31",
    "document_time": "16:55:43",
    "document_number": 1,
    "document_reference": "",
    "our_reference": "",
    "party_reference": "",
    "module_origin": 1,
    "warehouse_id": 1,
    "warehouse": {
        "code": 1,
        "description": "Armazém 1"
    },
    "target_warehouse_id": null,
    "target_warehouse": null,
    "origin_document_header_id": null,
    "origin_document_header": null,
    "salesman_id": null,
    "salesman": null,
    "party_id": 2,
    "party": {
        "class": 1601,
        "code": 2,
        "name": "Cliente Demo",
        "commercial_name": "",
        "fiscal_number": "123456789",
        "street1": "Rua Principal",
        "street2": "",
        "zip_code": "8800-123",
        "zip_locale": "Tavira"
    },
    "payment_term_id": 1,
    "payment_term": {
        "code": 1,
        "description": "Pronto Pagamento"
    },
    "payment_method_id": null,
    "payment_method": null,
    "line_details_count": 1,
    "lines_total_quantity": 1.0,
    "is_valued": true,
    "is_tax_included": false,
    "total_gross_amount": 10.0,
    "global_discount1": 0.0,
    "total_global_discount": 0.0,
    "total_line_discount": 0.0,
    "total_net_amount": 10.0,
    "total_taxes_amount": 2.3,
    "total_amount": 12.3,
    "total_document_amount": 12.3,
    "total_round_amount": 0.0,
    "total_due_amount": 0.0,
    "due_date": "2026-08-31",
    "header_text": "",
    "footer_text": "",
    "number_of_prints": 0,
    "is_converted": false,
    "is_transport_document": true,
    "load_date": "2026-08-31 17:00:37",
    "load_shipment_id": 1,
    "load_shipment": {
        "code": 1,
        "description": "Nossas instalações"
    },
    "ship_from_street1": "Morada do Estabelecimento",
    "ship_from_street2": "",
    "ship_from_city": "",
    "ship_from_zip_code": "8800-123",
    "ship_from_zip_locale": "Tavira",
    "ship_from_warehouse_id": 1,
    "ship_from_warehouse": {
        "code": 1,
        "description": "Armazém 1"
    },
    "unload_date": null,
    "unload_shipment_id": 5,
    "unload_shipment": {
        "code": 11,
        "description": "Morada do Destinatário"
    },
    "ship_to_street1": "Rua Principal",
    "ship_to_street2": "",
    "ship_to_city": "",
    "ship_to_zip_code": "8800-123",
    "ship_to_zip_locale": "Tavira",
    "ship_to_party_address_id": null,
    "ship_to_party_address": null,
    "has_withholding": false,
    "obs": ""
}
</code></pre>

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Apêndice

## Linha do Documento

<table data-search="false"><thead><tr><th width="173.5">Parâmetros</th><th width="94">Tipo</th><th width="357">Descrição</th><th width="120" data-type="checkbox">Obrigatório</th></tr></thead><tbody><tr><td>code</td><td>string</td><td><p>Identificador do produto a usar na linha</p><p></p><p>Pode referir-se tanto ao 'código' como ao 'código de barras' de um produto, ou ainda a um 'código alternativo' por este usado.</p></td><td>true</td></tr><tr><td>description</td><td>string</td><td><p>Descrição</p><p></p><p>Este valor, se preenchido, vai sobrepor-se à descrição na ficha do produto apenas na presente linha.</p></td><td>false</td></tr><tr><td>long_description</td><td>string</td><td>Descrição Alargada<br><br><mark style="color:orange;">Nota:  A utilização deste campo pode estar limitada por opções de configuração do CloudInvoice.</mark><br><mark style="color:orange;">Tamanho: 10000</mark></td><td>false</td></tr><tr><td>base_qty</td><td>float</td><td><p>Quantidade </p><p>Default: 1</p></td><td>false</td></tr><tr><td>line_discount1</td><td>float</td><td>Desconto de Linha #1<br>Valores entre 0 e 100</td><td>false</td></tr><tr><td>line_discount2</td><td>float</td><td>Desconto de Linha #2<br>Valores entre 0 e 100</td><td>false</td></tr><tr><td>line_unit_value</td><td>float</td><td><p>Preço Unitário</p><p></p><p>O valor fornecido deverá ser o Preço Unitário sem IVA se o documento estiver definido como contendo valores sem IVA. Deverá já incluir IVA caso contrário.</p></td><td>false</td></tr><tr><td>vat_tax_id</td><td>integer</td><td><p>Taxa de IVA</p><p><br>Consulte a tabela <a href="/documentacao-api/taxas/list#lista-de-tabelas-de-impostos">Tabelas de Impostos</a>.<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo está dependente da configuração <code>allow_tax_code_change_documents</code></p></td><td>false</td></tr></tbody></table>

{% tabs %}
{% tab title="Exemplo de Linha" %}

```json
{
    "code": "PROD1",
    "description": "Produto 1",
    "base_qty": 1,
    "line_unit_value": 100,
    "line_discount1": 10,
    "line_discount2": 5
}
```

{% endtab %}
{% endtabs %}

## Linhas do Documento de Origem

Estes objectos são usados nas emissões/conversões de Documentos.\
Contêm a identificação da linha de origem, assim como alguns valores opcionais que possam ser alterados durante o processo.

<table><thead><tr><th width="173.5">Parâmetros</th><th width="94">Tipo</th><th width="357">Descrição</th><th width="120" data-type="checkbox">Obrigatório</th></tr></thead><tbody><tr><td>id</td><td>integer</td><td>Linha do Documento de origem</td><td>true</td></tr><tr><td>base_qty</td><td>float</td><td><p>Quantidade</p><p><br>Se não definida, tomará, na maior parte dos casos, o valor da Quantidade da linha de origem.</p></td><td>false</td></tr><tr><td>line_unit_value</td><td>float</td><td><p>Preço Unitário</p><p></p><p>Se não definido, tomará, na maior parte dos casos, o valor do Preço Unitário da linha de origem.</p></td><td>false</td></tr></tbody></table>

## Pagamento do Documento

<table><thead><tr><th width="256.5">Parâmetros</th><th width="94">Tipo</th><th width="227">Descrição</th><th width="120" data-type="checkbox">Obrigatório</th></tr></thead><tbody><tr><td>payment_method_id</td><td>integer</td><td><p>Método de Pagamento</p><p><br>Consulte a tabela <a href="/documentacao-api/metodos-de-pagamento/list#lista-de-metodos-de-pagamento">Métodos de Pagamento</a>.</p></td><td>true</td></tr><tr><td>amount_received_currency</td><td>float</td><td>Valor do Pagamento<br><sub><mark style="color:$info;">Default: Valor em Dívida</mark></sub></td><td>false</td></tr><tr><td>payment_doc_reference</td><td>string</td><td><p>Referência do Pagamento</p><p></p><p>O preenchimento deste campo é obrigatório em alguns métodos de pagamento.</p></td><td>false</td></tr><tr><td>payment_doc_date</td><td>date</td><td>Data do Documento de Pagamento<br><sub><mark style="color:$info;">Format: YYYY-MM-DD</mark></sub></td><td>false</td></tr></tbody></table>

## Impressão do Documento

<table><thead><tr><th width="256.5">Parâmetros</th><th width="94">Tipo</th><th width="227">Descrição</th><th width="120" data-type="checkbox">Obrigatório</th></tr></thead><tbody><tr><td>print</td><td>boolean</td><td><p>Imprimir Documento</p><p></p><p>Apenas pode imprimir documentos finalizados/anulados.</p></td><td>true</td></tr><tr><td>format</td><td>string</td><td><p>Formato de Impressão</p><p></p><p>Caso não indique, será usado o formato configurado no documento.<br><br>Opções: <code>a4</code>, <code>a5</code>, <code>ticket</code></p></td><td>false</td></tr><tr><td>print_copies</td><td>number</td><td><p>Número de cópias</p><p></p><p>Caso não indique, será impresso o número de cópias configurado no documento.<br><br>Opções: <code>1-6</code> / <code>2via</code></p></td><td>false</td></tr><tr><td>print_copy</td><td>number</td><td><p>Indica o número da cópia a imprimir</p><p></p><p>Caso pretenda imprimir apenas uma cópia específica.<br><br>Opções: <code>1-6</code> / <code>2via</code></p></td><td>false</td></tr><tr><td>layout_id</td><td>integer</td><td><p>Layout de Impressão</p><p></p><p>Caso não indique, será usado o layout configurado no documento de acordo com o formato de impressão.</p></td><td>false</td></tr></tbody></table>

## Envio por E-mail do Documento

<table><thead><tr><th width="256.5">Parâmetros</th><th width="94">Tipo</th><th width="227">Descrição</th><th width="120" data-type="checkbox">Obrigatório</th></tr></thead><tbody><tr><td>email</td><td>boolean</td><td><p>Enviar por E-mail</p><p></p><p>Apenas pode imprimir documentos finalizados/anulados.</p></td><td>true</td></tr><tr><td>email_address</td><td>email</td><td>Endereço de Destino</td><td>true</td></tr><tr><td>email_subject</td><td>string</td><td>Assunto do E-mail</td><td>false</td></tr><tr><td>email_message</td><td>string</td><td>Mensagem do E-mail</td><td>false</td></tr><tr><td>email_cc</td><td>email</td><td>Endereço cc</td><td>false</td></tr><tr><td>email_bcc</td><td>email</td><td>Endereço bcc</td><td>false</td></tr></tbody></table>

## Dados para Transporte

<table data-search="false"><thead><tr><th width="206.5">Parâmetros</th><th width="110">Tipo</th><th width="282">Descrição</th><th width="120" data-type="checkbox">Obrigatório</th></tr></thead><tbody><tr><td>is_transport_document</td><td>boolean</td><td>É Documento de Transporte</td><td>true</td></tr><tr><td>load_date</td><td>datetime</td><td>Data de Carga<br><sub><mark style="color:$info;">Format: YYYY-MM-DD hh:mm:ss</mark></sub></td><td>false</td></tr><tr><td>load_shipment_id</td><td>integer</td><td><p>Local de Carga</p><p><br>Consulte Tabela Cargas e Descargas no Backoffice.</p></td><td>false</td></tr><tr><td>ship_from_warehouse_id</td><td>integer</td><td><p>Armazém de Origem</p><p><br>Consulte Tabela Armazéns no Backoffice.</p></td><td>false</td></tr><tr><td>ship_from_street1</td><td>string</td><td>Morada de Carga</td><td>false</td></tr><tr><td>ship_from_street2</td><td>string</td><td>Morada de Carga Linha 2</td><td>false</td></tr><tr><td>ship_from_zip_code</td><td>string</td><td>Código Postal (Origem)</td><td>false</td></tr><tr><td>ship_from_zip_locale</td><td>string</td><td>Localidade (Origem)</td><td>false</td></tr><tr><td>ship_from_city</td><td>email</td><td>Cidade (Origem)</td><td>false</td></tr><tr><td>vehicle_plate</td><td>string</td><td>Matrícula da Viatura</td><td>false</td></tr><tr><td>unload_date</td><td>datetime</td><td>Data de Descarga<br><sub><mark style="color:$info;">Format: YYYY-MM-DD hh:mm:ss</mark></sub></td><td>false</td></tr><tr><td>unload_shipment_id</td><td>integer</td><td><p>Local de Descarga</p><p><br>Consulte Tabela Cargas e Descargas no Backoffice.</p></td><td>false</td></tr><tr><td>ship_to_street1</td><td>string</td><td>Morada de Descarga</td><td>false</td></tr><tr><td>ship_to_street2</td><td>string</td><td>Morada de Descarga Linha 2</td><td>false</td></tr><tr><td>ship_to_zip_code</td><td>string</td><td>Código Postal (Destino)</td><td>false</td></tr><tr><td>ship_to_zip_locale</td><td>string</td><td>Localidade (Destino)</td><td>false</td></tr><tr><td>ship_to_city</td><td>string</td><td>Cidade (Destino)</td><td>false</td></tr><tr><td>ship_to_country_id</td><td>integer</td><td><p>País de Destino</p><p><br>Consulte Tabela <a href="/documentacao-api/paises/list#lista-de-paises">Países</a>.</p></td><td>false</td></tr></tbody></table>

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Recibos

Consulta e emissão de recibos.


# List

Fornece uma lista dos recibos existentes.

## Listar Recibos

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/receipts/`

#### Query Parameters

| Name             | Type    | Description                                                                                                                                                                                                                                                               |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| limit            | integer | Define o número de registos por pesquisa.                                                                                                                                                                                                                                 |
| offset           | integer | <p>Indica a posição inicial da pesquisa.</p><p>Retorna a lista de registos compreendida entre <code>offset</code> e <code>offset+limit</code>.</p>                                                                                                                        |
| ordering         | string  | <p>Define o campo e a direção a usar na pesquisa de registos.</p><p></p><p>Campos ordenáveis:</p><ul><li><code>id</code>, <code>doc\_key</code>, <code>document\_date</code>, <code>document\_time</code></li></ul><p>Use '-' antes do nome para ordem decrescente.</p>   |
| search           | string  | <p>Define o termo de pesquisa a utilizar na lista de registos. </p><p></p><p>Campos Pesquisados:</p><ul><li><code>doc\_key</code>, <code>document\_name</code>, <code>our\_reference</code>, <code>party\_fiscal\_number</code>, <code>party\_name</code>, etc.</li></ul> |
| document\_status | integer | <p>Estado do Documento</p><p></p><p>Consulte a tabela <a href="/documentacao-api/apendice#estados-dos-documentos-campo-document_status">Apêndice</a> para mais informação</p>                                                                                             |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/receipts/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "limit": 10,
    "offset": 0,
    "count": 117,
    "next": "http://localhost:8000/api/receipts/?limit=10&offset=10",
    "previous": null,
    "results": [
        {
            "id": 1,
            "doc_key": "REC A01/1",
            "document_date": "2026-03-09",
            "document_time": "13:05:09.205696",
            "document_number": 1,
            "party_reference": "",
            "module_origin": 1,
            "line_details_count": 1,
            "total_gross_amount": 1.0,
            "is_percentage_discount": true,
            "discount_percentage": 0.0,
            "total_net_amount": 0.8180337405,
            "total_amount": 1.0,
            "total_document_amount": 1.0,
            "total_received_amount": 1.0,
            "header_text": "",
            "footer_text": "",
            "number_of_prints": 7,
            "obs": "",
            "has_withholding": false,
            "document_id": 14,
            "document": {
                "code": "REC",
                "document_name": "Recibo",
                "ask_payment_onclose": true
            },
            "document_serie_id": 1,
            "document_serie": {
                "code": "A01",
                "description": "Serie A01"
            },
            "document_nature_id": 341,
            "document_nature": {
                "code": "RG",
                "description": "Recibo"
            },
            "document_status_id": 1202,
            "document_status": {
                "code": "F",
                "description": "Finalizado"
            },
            "salesman_id": null,
            "salesman": null,
            "party_id": 2,
            "party": {
                "class": 1601,
                "code": 2,
                "name": "Cliente Demo",
                "commercial_name": "",
                "fiscal_number": "123456789",
                "street1": "Rua Principal",
                "street2": "",
                "zip_code": "8800-000",
                "zip_locale": "Tavira"
            }
        },
        ...
    ]
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)

{% hint style="info" %}
**Notas:** Alguns dos campos do termo de pesquisa geral poderão ser incluídos mediante critérios específicos (Ex: Descrição será incluída na pesquisa geral apenas se o termo de pesquisa contiver 3 ou mais caracteres). Por defeito, o comportamento expectável será obter-se todos os items cujo o texto a pesquisar (search) esteja CONTIDO em pelo menos um dos campos incluídos na pesquisa geral.
{% endhint %}


# Emit

Emite um novo recibo.

## Criar Recibo

{% hint style="info" %}
Os Recibos podem ser emitidos fornecendo uma lista de documentos a incluir ou por valor a liquidar. Ao emitir por valor a liquidar, os documentos a incluir no recibo serão selecionados automaticamente, do mais antigo para o mais recente, até prefazer o valor a liquidar fornecido.
{% endhint %}

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/receipts/emit/`

#### Request Body

| Name                    | Type                                      | Description                                                                                                                                                                                                                                                                                                          |
| ----------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| customer\_id            | integer                                   | <p>Cliente</p><p></p><p>Consulte a tabela <a href="/documentacao-api/clientes/list">Clientes</a>.</p>                                                                                                                                                                                                                |
| documents               | array                                     | <p>Linhas do Recibo</p><p></p><p>Deverá conter uma lista de objectos, sendo que cada objecto poderá conter os parâmetros de um documento a incluir no Recibo conforme descritos no <a href="/documentacao-api/recibos/apendice#documents-do-recibo">Apêndice</a>.</p>                                                |
| total\_received\_amount | float                                     | <p>Valor a Liquidar</p><p></p><p>Seleção automática de documentos por valor a liquidar. <br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Apenas surtirá efeito se o campo 'documents' não for fornecido.</p>                                                                          |
| payments                | array                                     | <p>Pagamentos do Recibo</p><p></p><p>Deverá conter uma lista de objetos, sendo que cada objeto poderá conter os parâmetros de um pagamento conforme descritos no <a href="/documentacao-api/recibos/apendice#pagamento-do-recibo">Apêndice</a>.</p>                                                                  |
| finalize                | <p>boolean<br><em>Default: false</em></p> | <p>Finalizar o Recibo após criação</p><p></p><p>Finalizar o recibo de imediato. Deverá também fornecer dados relativos ao(s) pagamento(s) no campo <code>payments</code> equivalentes ao valor do recibo na sua totalidade.</p>                                                                                      |
| print                   | boolean                                   | <p>Imprimir Recibo após Emissão</p><p></p><p><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> O Recibo deverá estar finalizado.</p><p></p><p>Consulte os parâmetros disponíveis para impressão no <a href="/documentacao-api/recibos/apendice#impressao-do-recibo">Apêndice</a>.</p>          |
| email                   | boolean                                   | <p>Enviar por E-mail após Emissão</p><p></p><p><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> O Recibo deverá estar finalizado.</p><p></p><p>Consulte os parâmetros disponíveis para impressão no <a href="/documentacao-api/recibos/apendice#envio-por-e-mail-do-recibo">Apêndice</a>.</p> |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/receipts/emit/
    -d '{
        "customer_id": 2,
        "documents": [
            {
                "id": 5078,
                "amount": 1
            }
        ],
        "payments": [
            {
                "payment_method_id": 1
            }
        ],
        "finalize": true
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "doc_key": "REC A01/1",
    "document_date": "2026-03-11",
    "document_time": "10:25:10",
    "document_number": 1,
    "party_reference": "",
    "module_origin": 1,
    "party_id": 2,
    "party": {
        "class": 1601,
        "code": 2,
        "name": "Cliente Demo",
        "commercial_name": "",
        "fiscal_number": "123456789",
        "street1": "Rua Principal",
        "street2": "",
        "zip_code": "8800-000",
        "zip_locale": "Tavira"
    },
    "line_details_count": 1,
    "total_gross_amount": 1.0,
    "is_percentage_discount": true,
    "discount_percentage": 0.0,
    "total_net_amount": 0.8180337405,
    "total_amount": 1.0,
    "total_document_amount": 1.0,
    "total_received_amount": 1.0,
    "header_text": "",
    "footer_text": "",
    "number_of_prints": 0,
    "obs": "",
    "has_withholding": false,
    "document_nature_id": 341,
    "document_nature": {
        "code": "RG",
        "description": "Recibo"
    },
    "document_id": 14,
    "document": {
        "code": "REC",
        "document_name": "Recibo",
        "ask_payment_onclose": true
    },
    "document_serie_id": 1,
    "document_serie": {
        "code": "A01",
        "description": "Serie A01"
    },
    "document_status_id": 1202,
    "document_status": {
        "code": "F",
        "description": "Finalizado"
    },
    "salesman_id": null,
    "salesman": null
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Get

Obtém detalhes do recibo.

## Obter Recibo

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/receipts/:id/`

#### Path Parameters

| Name                                 | Type    | Description    |
| ------------------------------------ | ------- | -------------- |
| id<mark style="color:red;">\*</mark> | integer | O ID do Recibo |

#### Query Parameters

| Name     | Type    | Description                                                                                                  |
| -------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| extended | boolean | Inclui mais informação na resposta, incluindo listas de linhas, pagamentos e taxas (se aplicável) do recibo. |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/receipts/1/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "doc_key": "REC A01/1",
    "document_date": "2026-03-11",
    "document_time": "10:25:10",
    "document_number": 1,
    "party_reference": "",
    "module_origin": 1,
    "party_id": 2,
    "party": {
        "class": 1601,
        "code": 2,
        "name": "Cliente Demo",
        "commercial_name": "",
        "fiscal_number": "123456789",
        "street1": "Rua Principal",
        "street2": "",
        "zip_code": "8800-000",
        "zip_locale": "Tavira"
    },
    "line_details_count": 1,
    "total_gross_amount": 1.0,
    "is_percentage_discount": true,
    "discount_percentage": 0.0,
    "total_net_amount": 0.8180337405,
    "total_amount": 1.0,
    "total_document_amount": 1.0,
    "total_received_amount": 1.0,
    "header_text": "",
    "footer_text": "",
    "number_of_prints": 0,
    "obs": "",
    "has_withholding": false,
    "document_nature_id": 341,
    "document_nature": {
        "code": "RG",
        "description": "Recibo"
    },
    "document_id": 14,
    "document": {
        "code": "REC",
        "document_name": "Recibo",
        "ask_payment_onclose": true
    },
    "document_serie_id": 1,
    "document_serie": {
        "code": "A01",
        "description": "Série A01"
    },
    "document_status_id": 1202,
    "document_status": {
        "code": "F",
        "description": "Finalizado"
    },
    "salesman_id": null,
    "salesman": null
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Finalize

Finaliza recibo com possibilidade de impressão ou envio de e-mail.

## Finalizar Recibo

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/receipts/:id/finalize/`

#### Path Parameters

| Name                                 | Type    | Description  |
| ------------------------------------ | ------- | ------------ |
| id<mark style="color:red;">\*</mark> | integer | ID do Recibo |

#### Request Body

| Name     | Type    | Description                                                                                                                                                                                                                                         |
| -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| payments | Array   | <p>Pagamentos do Recibo</p><p></p><p>Deverá conter uma lista de objetos, sendo que cada objeto poderá conter os parâmetros de um pagamento conforme descritos no <a href="/documentacao-api/recibos/apendice#pagamento-do-recibo">Apêndice</a>.</p> |
| print    | boolean | <p>Imprimir Recibo após a Finalização</p><p></p><p>O ficheiro PDF do Recibo é gerado ao finalizar.<br><br>Consulte os parâmetros disponíveis para impressão no <a href="/documentacao-api/recibos/apendice#impressao-do-recibo">Apêndice</a>.</p>   |
| email    | boolean | <p>Enviar por E-mail após a Finalização</p><p></p><p>Consulte os parâmetros disponíveis para impressão no <a href="/documentacao-api/recibos/apendice#envio-por-e-mail-do-recibo">Apêndice</a>.</p>                                                 |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/receipts/1/finalize/
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

<pre class="language-json"><code class="lang-json">{
    "id": 1,
    "doc_key": "REC A01/1",
    "document_date": "2026-03-17",
    "document_time": "17:11:11",
    "document_number": 1,
    "party_reference": "",
    "module_origin": 1,
    "party_id": 2,
    "party": {
        "class": 1601,
        "code": 2,
        "name": "Cliente Demo",
        "commercial_name": "",
        "fiscal_number": "123456789",
        "street1": "",
        "street2": "",
        "zip_code": "8800-000",
        "zip_locale": "Tavira"
    },
    "line_details_count": 1,
    "total_gross_amount": 100.0,
    "is_percentage_discount": true,
    "discount_percentage": 0.0,
    "total_net_amount": 100.0,
    "total_amount": 100.0,
    "total_document_amount": 100.0,
    "total_received_amount": 100.0,
    "header_text": "",
    "footer_text": "",
    "number_of_prints": 0,
    "obs": "",
    "has_withholding": false,
    "document_nature_id": 341,
    "document_nature": {
        "code": "RG",
        "description": "Recibo"
    },
    "document_id": 14,
    "document": {
        "code": "REC",
        "document_name": "Recibo",
        "ask_payment_onclose": true
    },
    "document_serie_id": 1,
    "document_serie": {
        "code": "A01",
        "description": "Serie A01"
    },
<strong>    "document_status_id": 1202,
</strong><strong>    "document_status": {
</strong><strong>        "code": "F",
</strong><strong>        "description": "Finalizado"
</strong><strong>    },
</strong>    "salesman_id": 1,
    "salesman": {
        "code": 1,
        "salesman_name": "Vendedor 1"
    }
}
</code></pre>

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Delete

Apaga um recibo em preparação.

## Apagar Recibo

{% hint style="warning" %}
Atenção! Esta ação apenas pode ser executada em recibos ainda em preparação.
{% endhint %}

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/receipts/:id/delete/`

#### Path Parameters

| Name                                 | Type    | Description                           |
| ------------------------------------ | ------- | ------------------------------------- |
| id<mark style="color:red;">\*</mark> | integer | O ID do recibo que pretende eliminar. |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/receipts/1/delete/
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Linhas


# List

Fornece uma lista das linhas do recibo.

## Lista das Linhas do Recibo

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/receipts/:id/details/`

#### Query Parameters

| Name   | Type    | Description                                                                                                                                        |
| ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| limit  | integer | Define o número de registos por pesquisa.                                                                                                          |
| offset | integer | <p>Indica a posição inicial da pesquisa.</p><p>Retorna a lista de registos compreendida entre <code>offset</code> e <code>offset+limit</code>.</p> |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/receipts/1/details/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "limit": 10,
    "offset": 0,
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "line_number": 1,
            "document_date": "2025-07-21",
            "document_due_date": "2025-07-21",
            "description": "Factura",
            "doc_total_amount": 100.0,
            "total_received_amount": 100.0,
            "total_net_amount": 100.0,
            "total_discount_amount": 0.0,
            "total_amount": 100.0,
            "document_header_id": 1,
            "document_header": {
                "doc_key": "FAC A01/1",
                "document_name": "Factura"
            }
        }
    ]
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)

{% hint style="info" %}
**Notas:** Alguns dos campos do termo de pesquisa geral poderão ser incluídos mediante critérios específicos (Ex: Descrição será incluída na pesquisa geral apenas se o termo de pesquisa contiver 3 ou mais caracteres). Por defeito, o comportamento expectável será obter-se todos os items cujo o texto a pesquisar (search) esteja CONTIDO em pelo menos um dos campos incluídos na pesquisa geral.
{% endhint %}


# Pagamentos


# List

Fornece uma lista dos pagamentos do recibo.

## Listar Pagamentos do Recibo

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/receipts/:id/payments/`

#### Query Parameters

| Name   | Type    | Description                                                                                                                                        |
| ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| limit  | integer | Define o número de registos por pesquisa.                                                                                                          |
| offset | integer | <p>Indica a posição inicial da pesquisa.</p><p>Retorna a lista de registos compreendida entre <code>offset</code> e <code>offset+limit</code>.</p> |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/receipts/1/payments/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "limit": 10,
    "offset": 0,
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "payment_date": "2026-03-17T17:11:11.697406Z",
            "total_payment": 100.0,
            "payment_method_id": 1,
            "payment_method": {
                "code": 1,
                "description": "Dinheiro"
            }
        }
    ]
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)

{% hint style="info" %}
**Notas:** Alguns dos campos do termo de pesquisa geral poderão ser incluídos mediante critérios específicos (Ex: Descrição será incluída na pesquisa geral apenas se o termo de pesquisa contiver 3 ou mais caracteres). Por defeito, o comportamento expectável será obter-se todos os items cujo o texto a pesquisar (search) esteja CONTIDO em pelo menos um dos campos incluídos na pesquisa geral.
{% endhint %}


# Ações


# Annul

Anula recibo finalizado.

## Anular Recibo

{% hint style="danger" %}
A anulação de um recibo não poderá ser revertida em circunstância alguma.
{% endhint %}

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/receipts/:id/annul/`

#### Path Parameters

| Name                                 | Type    | Description  |
| ------------------------------------ | ------- | ------------ |
| id<mark style="color:red;">\*</mark> | integer | ID do Recibo |

#### Request Body

| Name                                             | Type    | Description                                                                                                                                                                                    |
| ------------------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| status\_reason<mark style="color:red;">\*</mark> | string  | Motivo da Anulação                                                                                                                                                                             |
| print                                            | boolean | <p>Imprimir Recibo após Anulação</p><p></p><p>Consulte os parâmetros disponíveis para impressão no <a href="/documentacao-api/recibos/apendice#impressao-do-recibo">Apêndice</a>.</p>          |
| email                                            | boolean | <p>Enviar por E-mail após Anulação</p><p></p><p>Consulte os parâmetros disponíveis para impressão no <a href="/documentacao-api/recibos/apendice#envio-por-e-mail-do-recibo">Apêndice</a>.</p> |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/receipts/1/annul/
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

<pre class="language-json"><code class="lang-json">{
    "id": 1,
    "doc_key": "REC A01/1",
    "document_date": "2026-03-11",
    "document_time": "10:25:10",
    "document_number": 1,
    "party_reference": "",
    "module_origin": 1,
    "party_id": 2,
    "party": {
        "class": 1601,
        "code": 2,
        "name": "Cliente Demo",
        "commercial_name": "",
        "fiscal_number": "123456789",
        "street1": "Rua Principal",
        "street2": "",
        "zip_code": "8800-000",
        "zip_locale": "Tavira"
    },
    "line_details_count": 1,
    "total_gross_amount": 1.0,
    "is_percentage_discount": true,
    "discount_percentage": 0.0,
    "total_net_amount": 0.8180337405,
    "total_amount": 1.0,
    "total_document_amount": 1.0,
    "total_received_amount": 1.0,
    "header_text": "",
    "footer_text": "",
    "number_of_prints": 0,
    "obs": "",
    "has_withholding": false,
    "document_nature_id": 341,
    "document_nature": {
        "code": "RG",
        "description": "Recibo"
    },
    "document_id": 14,
    "document": {
        "code": "REC",
        "document_name": "Recibo",
        "ask_payment_onclose": true
    },
    "document_serie_id": 1,
    "document_serie": {
        "code": "A01",
        "description": "Série A01"
    },
<strong>    "document_status_id": 1203,
</strong><strong>    "document_status": {
</strong><strong>        "code": "A",
</strong><strong>        "description": "Anulado"
</strong><strong>    },
</strong>    "salesman_id": null,
    "salesman": null
}
</code></pre>

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Print

Gera ficheiro PDF do recibo para impressão.

## Imprimir Recibo

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/receipts/:id/print/`

#### Path Parameters

| Name                                 | Type    | Description  |
| ------------------------------------ | ------- | ------------ |
| id<mark style="color:red;">\*</mark> | integer | ID do Recibo |

#### Request Body

| Name  | Type    | Description                                                                                                                                                                                                                                                                                    |
| ----- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| print | boolean | <p>Imprimir Recibo</p><p></p><p><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> O Recibo deverá estar finalizado.</p><p></p><p>Consulte os parâmetros disponíveis para impressão no <a href="/documentacao-api/recibos/apendice#impressao-do-recibo">Apêndice</a>.</p> |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/receipts/1/print/
    -d '{
        "print": true,
        "print_copy": 3
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "doc_key": "REC A01/1",
    "print": {
        "filename": "RG__REC_A01_1__2026_03_17_1773830259.pdf",
        "url": "https://app.cloudinvoice/downloads/xxxxxxxxxx-xxxx-xxx-xxxx-xxxxxxxxx/"
    }
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Email

Envia recibo finalizado/anulado por E-mail.

## Enviar Recibo por E-mail

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/receipts/:id/email/`

#### Path Parameters

| Name                                 | Type    | Description  |
| ------------------------------------ | ------- | ------------ |
| id<mark style="color:red;">\*</mark> | integer | ID do Recibo |

#### Request Body

| Name  | Type    | Description                                                                                                                                                                                                                                                                                             |
| ----- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| email | boolean | <p>Enviar por E-mail</p><p></p><p><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> O Recibo deverá estar finalizado.</p><p></p><p>Consulte os parâmetros disponíveis para impressão no <a href="/documentacao-api/recibos/apendice#envio-por-e-mail-do-recibo">Apêndice</a>.</p> |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/receipts/1/email/
    -d '{
        "email": true,
        "email_address": "email@address.com"
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "doc_key": "REC A01/1",
    "print": {
        "filename": "RG__REC_A01_1__2026_03_17_1773830259.pdf",
        "url": "https://app.cloudinvoice/downloads/xxxxxxxxxx-xxxx-xxx-xxxx-xxxxxxxxx/"
    }
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Apêndice

## Documento do Recibo

<table><thead><tr><th width="173.5">Parâmetros</th><th width="94">Tipo</th><th width="357">Descrição</th><th width="120" data-type="checkbox">Obrigatório</th></tr></thead><tbody><tr><td>id</td><td>integer</td><td><p>ID do Documento a usar na Linha</p><p></p><p>Pode referir-se tanto ao 'código' como ao 'código de barras' de um produto, ou ainda a um 'código alternativo' por este usado.</p></td><td>true</td></tr><tr><td>amount</td><td>float</td><td><p>Valor a Liquidar</p><p></p><p>Se não fornecido, a linha será lançada com o valor total ainda por liquidar do documento.</p></td><td>false</td></tr></tbody></table>

{% tabs %}
{% tab title="Exemplo de Linha" %}

```json
{
    "id": 1,
    "amount": 100.0
}
```

{% endtab %}
{% endtabs %}

## Pagamento do Recibo

<table><thead><tr><th width="256.5">Parâmetros</th><th width="94">Tipo</th><th width="227">Descrição</th><th width="120" data-type="checkbox">Obrigatório</th></tr></thead><tbody><tr><td>payment_method_id</td><td>integer</td><td><p>Método de Pagamento</p><p><br>Consulte a tabela <a href="/documentacao-api/metodos-de-pagamento/list#lista-de-metodos-de-pagamento">Métodos de Pagamento</a>.</p></td><td>true</td></tr><tr><td>amount_received_currency</td><td>float</td><td>Valor do Pagamento<br>Default: Valor em Dívida</td><td>false</td></tr><tr><td>payment_doc_reference</td><td>string</td><td><p>Referência do Pagamento</p><p></p><p>O preenchimento deste campo é obrigatório em alguns métodos de pagamento.</p></td><td>false</td></tr><tr><td>payment_doc_date</td><td>date</td><td><p>Data do Documento de Pagamento </p><p>(Ex: Data do Cheque bancário)</p></td><td>false</td></tr></tbody></table>

## Impressão do Recibo

<table><thead><tr><th width="256.5">Parâmetros</th><th width="94">Tipo</th><th width="227">Descrição</th><th width="120" data-type="checkbox">Obrigatório</th></tr></thead><tbody><tr><td>print</td><td>boolean</td><td><p>Imprimir Documento</p><p></p><p>Apenas pode imprimir documentos finalizados/anulados.</p></td><td>true</td></tr><tr><td>format</td><td>string</td><td><p>Formato de Impressão:</p><p>Opções: [a4/a5/ticket].</p><p></p><p>Caso não indique, será usado o formato configurado no documento.</p></td><td>false</td></tr><tr><td>print_copies</td><td>number</td><td><p>Número de cópias.</p><p>Opções: [1-6] / 2via.</p><p></p><p>Caso não indique, será impresso o número de cópias configurado no documento.</p></td><td>false</td></tr><tr><td>print_copy</td><td>number</td><td><p>Indica o número da cópia a imprimir</p><p>Opções: [1-6] / 2via.</p><p></p><p>Caso pretenda imprimir apenas uma cópia específica (Ex: Imprimir apenas triplicado)</p></td><td>false</td></tr><tr><td>layout_id</td><td>integer</td><td><p>Layout de Impressão</p><p></p><p>Caso não indique, será usado o layout configurado no documento de acordo com o formato de impressão.</p></td><td>false</td></tr></tbody></table>

## Envio por E-mail do Recibo

<table><thead><tr><th width="256.5">Parâmetros</th><th width="94">Tipo</th><th width="227">Descrição</th><th width="120" data-type="checkbox">Obrigatório</th></tr></thead><tbody><tr><td>email</td><td>boolean</td><td><p>Enviar por E-mail</p><p></p><p>Apenas pode imprimir documentos finalizados/anulados.</p></td><td>true</td></tr><tr><td>email_address</td><td>email</td><td>Endereço de Destino</td><td>true</td></tr><tr><td>email_subject</td><td>string</td><td>Assunto do E-mail</td><td>false</td></tr><tr><td>email_message</td><td>string</td><td>Mensagem do E-mail</td><td>false</td></tr><tr><td>email_cc</td><td>email</td><td>Endereço cc</td><td>false</td></tr><tr><td>email_bcc</td><td>email</td><td>Endereço bcc</td><td>false</td></tr></tbody></table>

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Tipos de Documentos


# List

Fornece uma lista dos tipos de documentos existentes.

## Listar Tipos de Documentos

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/documents/configs/`

#### Query Parameters

<table data-search="false"><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>limit</td><td>integer</td><td>Define o número de registos por pesquisa.</td></tr><tr><td>offset</td><td>integer</td><td><p>Indica a posição inicial da pesquisa.</p><p>Retorna a lista de registos compreendida entre <code>offset</code> e <code>offset+limit</code>.</p></td></tr><tr><td>ordering</td><td>string<br><sub><mark style="color:$info;">Default: "code"</mark></sub></td><td><p>Define o campo e a direção a usar na pesquisa de países. </p><p></p><p>Campos ordenáveis:</p><ul><li><code>id</code>, <code>code</code>, <code>document_name</code></li></ul><p>Use '-' antes do nome para ordem decrescente.</p></td></tr><tr><td>search</td><td>string</td><td><p>Define o termo de pesquisa a utilizar na lista de registos. </p><p></p><p>Campos Pesquisados:</p><ul><li><code>code</code>, <code>document_name</code>, <code>description</code></li></ul></td></tr><tr><td>code</td><td>string</td><td><p>Código do Distrito</p><p></p><p>Sufixos disponíveis:</p><ul><li><code>__search</code>: para pesquisa parcial</li></ul></td></tr><tr><td>document_name</td><td>string</td><td><p>Nome do Documento</p><p></p><p>Sufixos disponíveis:</p><ul><li><code>__search</code>: para pesquisa parcial</li></ul></td></tr><tr><td>is_hash_signed</td><td>boolean</td><td>Documento Assinado</td></tr><tr><td>is_valued</td><td>boolean</td><td>Documento Valorizado</td></tr><tr><td>is_self_billing</td><td>boolean</td><td>Documento de Auto-Facturação</td></tr><tr><td>is_plafond_document</td><td>boolean</td><td>Documento de Plafond</td></tr><tr><td>is_global_transport</td><td>boolean</td><td>Documento de Transporte Global</td></tr><tr><td>is_credit_document</td><td>boolean</td><td>Documento de Crédito</td></tr><tr><td>is_return_document</td><td>boolean</td><td>Documento de Devolução</td></tr><tr><td>is_eu_sales</td><td>boolean</td><td><p>Documento de Venda à Distância</p><p></p><p><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Disponível apenas se o módulo "Regime de Vendas à Distância" estiver activo.</p></td></tr></tbody></table>

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/documents/configs/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "limit": 10,
    "offset": 0,
    "count": 85,
    "next": "https://api.cloudinvoice.net/documents/configs/?limit=10&offset=10",
    "previous": null,
    "results": [
        {
            "id": 56,
            "code": "ACX",
            "document_name": "Abertura de Caixa",
            "document_type_id": 295,
            "document_type": {
                "code": "CX",
                "description": "Caixa"
            },
            "party_class_id": 1600,
            "party_class": {
                "code": "N",
                "description": "(Nenhuma)"
            },
            "document_nature_id": 701,
            "document_nature": {
                "code": "ACX",
                "description": "Abertura de Caixa"
            },
            "document_layout_type_id": 915,
            "document_layout_type": {
                "code": "CX",
                "description": "Caixa"
            },
            "saft_doc_category_id": 281,
            "saft_doc_category": {
                "code": "N",
                "description": "Documento Interno/Não-SAFT-PT"
            }
        },
        {
            "id": 42,
            "code": "AST",
            "document_name": "Acerto de Stock",
            "document_type_id": 293,
            "document_type": {
                "code": "S",
                "description": "Stock"
            },
            "party_class_id": 1600,
            "party_class": {
                "code": "N",
                "description": "(Nenhuma)"
            },
            "document_nature_id": 506,
            "document_nature": {
                "code": "AST",
                "description": "Acerto de Stock"
            },
            "document_layout_type_id": 913,
            "document_layout_type": {
                "code": "S",
                "description": "Produtos"
            },
            "saft_doc_category_id": 281,
            "saft_doc_category": {
                "code": "N",
                "description": "Documento Interno/Não-SAFT-PT"
            }
        },
        ...
    ]
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Get

Obtém detalhes do tipo de documento.

## Obter Tipo de Documento

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/documents/configs/:id/`

#### Path Parameters

| Name                                 | Type    | Description               |
| ------------------------------------ | ------- | ------------------------- |
| id<mark style="color:red;">\*</mark> | integer | O ID do Tipo de Documento |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/documents/configs/1/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

<pre class="language-json"><code class="lang-json">{
    "id": 1,
    "code": "FAC",
    "document_name": "Factura",
    "document_nature_id": 301,
    "document_nature": {
        "code": "FT",
        "description": "Factura"
    },
    "document_type_id": 291,
    "document_type": {
        "code": "V",
        "description": "Venda"
    },
    "party_class_id": 1601,
    "party_class": {
        "code": "C",
        "description": "Cliente"
    },
    "saft_doc_category_id": 282,
    "saft_doc_category": {
        "code": "V",
        "description": "Vendas/Comerciais"
    },
    "document_layout_type_id": 911,
    "document_layout_type": {
        "code": "V",
        "description": "Vendas"
    },
    "stock_behavior_type_id": 1122,
    "stock_behavior_type": {
        "code": "X",
        "description": "Existência"
    },
    "stock_movement_type_id": 1103,
    "stock_movement_type": {
        "code": "S",
        "description": "Saída"
    },
    "till_movement_type_id": 1731,
    "till_movement_type": {
        "code": "N",
        "description": "Nenhum"
    },
    "price_line_to_use_id": 3251,
<strong>    "price_line_to_use": {
</strong>        "code": "V",
        "description": "Venda"
    },
    "price_line_id": 1,
    "price_line": {
        "code": 1,
        "description": "Preço de Venda 1"
    },
    "is_hash_signed": true,
    "upd_last_cost_price": false,
    "upd_average_cost_price": false,
    "is_tax_included": false,
    "is_valued": true,
    "is_global_transport": false,
    "is_credit_document": false,
    "is_self_billing": false,
    "is_plafond_document": false,
    "is_return_document": false,
    "ask_payment_onclose": false,
    "at_cud_serie_suffix": ""
}
</code></pre>

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Séries de Documentos

{% hint style="danger" %}
As Série de Documentos precisam de, desde dia 1 de Janeiro de 2023, ser comunicadas à Autoridade Tributária de modo a lhes serem atribuídos códigos ATCUD.
{% endhint %}


# List

Fornece uma lista das séries de documentos existentes.

## Listar Séries de Documentos

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/series/`

#### Query Parameters

| Name                  | Type                                                                          | Description                                                                                                                                                                                                                                                |
| --------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| limit                 | integer                                                                       | Define o número de registos por pesquisa.                                                                                                                                                                                                                  |
| offset                | integer                                                                       | <p>Indica a posição inicial da pesquisa.</p><p>Retorna a lista de registos compreendida entre <code>offset</code> e <code>offset+limit</code>.</p>                                                                                                         |
| ordering              | <p>string<br><sub><mark style="color:$info;">Default: "code"</mark></sub></p> | <p>Define o campo e a direção a usar na pesquisa de registos.</p><p></p><p>Campos ordenáveis:</p><ul><li><code>id</code>, <code>code</code>, <code>description</code>, <code>location</code></li></ul><p>Use '-' antes do nome para ordem decrescente.</p> |
| search                | string                                                                        | <p>Define o termo de pesquisa a utilizar na lista de registos. </p><p></p><p>Campos Pesquisados:</p><ul><li><code>description</code>, <code>location</code></li></ul>                                                                                      |
| code                  | string                                                                        | <p>Código da Série</p><p></p><p>Sufixos disponíveis:</p><ul><li><code>\_\_search</code>: para pesquisa parcial</li></ul>                                                                                                                                   |
| description           | string                                                                        | <p>Descrição</p><p></p><p>Sufixos disponíveis:</p><ul><li><code>\_\_search</code>: para pesquisa parcial</li></ul>                                                                                                                                         |
| location              | integer                                                                       | Localização                                                                                                                                                                                                                                                |
| is\_closed            | boolean                                                                       | Série Fechada                                                                                                                                                                                                                                              |
| is\_cash\_vat\_scheme | boolean                                                                       | Série do Regime de IVA de Caixa                                                                                                                                                                                                                            |
| is\_self\_billing     | boolean                                                                       | <p>Série de Auto-Facturação</p><p></p><p><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Esta opção estará disponível apenas se o módulo de Auto-Facturação estiver activo.</p>                                                    |
| is\_electronic\_serie | boolean                                                                       | <p>Série de Facturação Electrónica</p><p></p><p><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Esta opção estará disponível apenas se o módulo de Facturação Electrónica estiver activo.</p>                                      |
| is\_edi\_serie        | boolean                                                                       | <p>Série EDI</p><p></p><p><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Esta opção estará disponível apenas se o módulo EDI (Electronic Data Interchange) estiver activo.</p>                                                    |
| is\_eu\_sales\_serie  | boolean                                                                       | <p>Série para Vendas Intracomunitárias</p><p></p><p><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Esta opção estará disponível apenas se o módulo de Regime de Vendas à Distância estiver activo.</p>                            |
| is\_oss\_serie        | boolean                                                                       | <p>Série para OSS (One Stop Shop)</p><p></p><p><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Esta opção estará disponível apenas se o módulo de Regime de Vendas à Distância estiver activo.</p>                                 |
| is\_offline\_serie    | boolean                                                                       | <p>Série Offline</p><p></p><p><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Esta opção estará disponível apenas se o módulo POS Offline estiver activo.</p>                                                                      |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/series/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "limit": 10,
    "offset": 0,
    "count": 4,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 3,
            "code": "A01",
            "description": "Série A01",
            "initial_date": null,
            "expiration_date": "2999-12-31T23:59:00Z",
            "is_closed": true,
            "document_serie_type_id": 901,
            "document_serie_type": {
                "code": "P",
                "description": "Documentos Produzidos na Aplicação"
            },
            "location_id": 1,
            "location": {
                "code": 1,
                "description": "Localização 1"
            }
        },
        {
            "id": 4,
            "code": "A02",
            "description": "Série A02",
            "initial_date": "2023-01-03T11:58:00Z",
            "expiration_date": null,
            "is_closed": false,
            "document_serie_type_id": 901,
            "document_serie_type": {
                "code": "P",
                "description": "Documentos Produzidos na Aplicação"
            },
            "location_id": 1,
            "location": {
                "code": 1,
                "description": "Localização 1"
            }
        },
        ...
    ]
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Create

Cria uma nova série de documentos.

## Criar Série de Documentos

{% hint style="danger" %}
As Série de Documentos precisam, desde dia 1 de Janeiro de 2023, ser comunicadas à Autoridade Tributária de modo a lhes serem atribuídos códigos ATCUD.\
\
Certifique-se que já obteve as suas credenciais WSE no portal dao Autoridade Tributária e as inseriu no BackOffice CloudInvoice em:\
&#x20;            **Configurações → Autoridade Tributária → Comunicação de Séries ATCUD**\
antes de tentar criar uma Série de Documentos
{% endhint %}

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/series/new/`

#### Request Body

<table data-search="false"><thead><tr><th>Name</th><th width="249">Type</th><th>Description</th></tr></thead><tbody><tr><td>code<mark style="color:red;">*</mark></td><td>string<br><sub><mark style="color:$info;">Valor Único</mark></sub></td><td>Código da Série<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Códigos começados por <code>AT</code> não são permitidos pela Autoridade Tributária.</td></tr><tr><td>description<mark style="color:red;">*</mark></td><td>string</td><td>Descrição</td></tr><tr><td>document_serie_type_id</td><td>integer</td><td>Tipo de Série<br><br>Consulte a tabela <a href="/documentacao-api/apendice#tipos-de-series-de-documentos-campo-document_serie_type">Apêndice</a> para saber mais.</td></tr><tr><td>initial_date</td><td>date<br><sub><mark style="color:$info;">Format: yyyy-mm-dd</mark></sub></td><td>Data de Início<br><br>Quando não fornecido, assume a data atual.</td></tr><tr><td>expiration_date</td><td>date<br><sub><mark style="color:$info;">Format: yyyy-mm-dd</mark></sub></td><td>Data de Expiração</td></tr><tr><td>config_document</td><td>list</td><td>Lista de Documentos<br><br>IDs dos Tipos de Documentos para os quais serão criadas numerações na Série.<br><br>Consulte a tabela <a href="/documentacao-api/tipos-de-documentos/list">Tipos de Documentos</a> para saber mais.</td></tr><tr><td>is_cash_vat_scheme</td><td>boolean</td><td>Regime de IVA de Caixa<br><br>Série para usar em Documentos ao abrigo do Regime de IVA de Caixa.</td></tr><tr><td>is_eu_sales_serie</td><td>boolean</td><td>Regime de Vendas à Distância<br><br>Série para usar em Documentos ao abrigo do Regime de Vendas à Distância.<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização destes séries requer o módulo de Vendas à Distância.</td></tr><tr><td>is_oss_serie</td><td>boolean</td><td>Série OSS (One-Stop-Shop)<br><br>Série para usar em Documentos ao abrigo do Regime de Vendas à Distância, com OSS.<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização destes séries requer o módulo de Vendas à Distância.</td></tr><tr><td>is_offline_serie</td><td>boolean</td><td>Série Offline<br><br>Série para usar em Documentos  gerados no módulo offline do POS CloudInvoice.<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização destes séries requer o módulo Offline.</td></tr></tbody></table>

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/series/new/
    -d '{
        "code": "A01",
        "description": "Serie API",
        "config_document": [1, 2, 3]
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 3,
    "code": "A01",
    "description": "Serie API",
    "document_serie_type_id": 901,
    "document_serie_type": {
        "code": "P",
        "description": "Documentos Produzidos na Aplicação"
    },
    "is_at_cud_serie": true,
    "initial_date": "2026-05-19 10:46:38",
    "expiration_date": null,
    "is_closed": false,
    "closed_user_id": null,
    "closed_date": null,
    "closed_reason": "",
    "location_id": 1,
    "location": {
        "code": 1,
        "description": "Localização 1"
    },
    "is_cash_vat_scheme": false
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Get

Obtém detalhes da série de documentos.

## Obter Série de Documentos

{% hint style="warning" %}
Os campos presentes na resposta poderão variar consoante os módulos activos na sua licença.\
`is_self_billing`, `is_electronic_serie`, `is_edi_serie`, `is_oss_serie`, `is_eu_sales_serie` e `is_offline_serie` são alguns dos exemplos de campos que estão dependentes dos respectivos módulos estarem activos.
{% endhint %}

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/series/:id/`

#### Path Parameters

| Name                                 | Type    | Description                 |
| ------------------------------------ | ------- | --------------------------- |
| id<mark style="color:red;">\*</mark> | integer | O ID da Série de Documentos |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/series/3/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 3,
    "code": "A01",
    "description": "Serie API",
    "document_serie_type_id": 901,
    "document_serie_type": {
        "code": "P",
        "description": "Documentos Produzidos na Aplicação"
    },
    "is_at_cud_serie": true,
    "initial_date": "2026-05-19 11:00:20",
    "expiration_date": null,
    "is_closed": false,
    "closed_user_id": null,
    "closed_date": null,
    "closed_reason": "",
    "location_id": 1,
    "location": {
        "code": 1,
        "description": "Localização 1"
    },
    "is_cash_vat_scheme": false,
    "document_numbers": [
        {
            "id": 21,
            "at_cud": "BEKPTXCT",
            "last_number": 0,
            "temporary_last_number": 0,
            "document_id": 1,
            "document": {
                "code": "FAC",
                "document_name": "Factura"
            }
        },
        ...
    ]
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Numerações


# List

Fornece uma lista das numerações de documentos existentes na série.

## Listar Numerações de Documentos

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/series/:serie_id/numbers/`

#### Path Parameters

| Name      | Type    | Description |
| --------- | ------- | ----------- |
| serie\_id | integer | ID da Série |

#### Query Parameters

| Name   | Type    | Description                                                                                             |
| ------ | ------- | ------------------------------------------------------------------------------------------------------- |
| limit  | integer | Define o número de linhas por pesquisa.                                                                 |
| offset | integer | Indica a posição inicial da pesquisa. Retorna a lista de linhas compreendida entre offset:offset+limit. |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/series/1/numbers/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "limit": 10,
    "offset": 0,
    "count": 32,
    "next": "https://api.cloudinvoice.net/series/1/numbers/?limit=10&offset=10",
    "previous": null,
    "results": [
        {
            "id": 1,
            "at_cud": "",
            "last_number": 0,
            "temporary_last_number": 0,
            "document_id": 1,
            "document": {
                "code": "FAC",
                "document_name": "Factura"
            }
        },
        {
            "id": 2,
            "at_cud": "",
            "last_number": 0,
            "temporary_last_number": 0,
            "document_id": 2,
            "document": {
                "code": "FSI",
                "document_name": "Factura Simplificada"
            }
        },
        ...
    ]
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Create

Cria numeração de documento na série.

## Criar Numeração de Documentos

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/series/:serie_id/numbers/new/`

#### Path Parameters

| Name      | Type    | Description               |
| --------- | ------- | ------------------------- |
| serie\_id | integer | ID da Série de Documentos |

#### Request Body

| Name         | Type    | Description                                                                                                                                     |
| ------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| document\_id | integer | <p>Tipo de Documento<br><br>Consulte a tabela <a href="/documentacao-api/tipos-de-documentos/list">Tipos de Documentos</a> para saber mais.</p> |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/series/1/numbers/new/
    -d '{
        "document": 2
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 2,
    "document_serie_id": 1,
    "document_serie": {
        "code": "A01",
        "description": "Série A01"
    },
    "document_id": 2,
    "document": {
        "code": "FSI",
        "document_name": "Factura Simplificada"
    },
    "location_id": 1,
    "location": {
        "code": 1,
        "description": "Localização 1"
    },
    "at_cud": "OYVYADQH",
    "last_number": 0,
    "temporary_last_number": 0,
    "last_doc_date": null
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Clientes

Um Cliente representa uma entidade, empresa ou pessoa. Os clientes podem ser utilizados em documentos de venda e emissão de recibos. Também podem ser geridas as contas-correntes e saldos de cada um.


# List

Fornece uma lista de todos os clientes existentes.

## Listar Clientes

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/customers/`

#### Query Parameters

<table data-search="false"><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>limit</td><td>integer</td><td>Define o número de registos por pesquisa.</td></tr><tr><td>offset</td><td>integer</td><td><p>Indica a posição inicial da pesquisa.</p><p>Retorna a lista de registos compreendida entre <code>offset</code> e <code>offset+limit</code>.</p></td></tr><tr><td>ordering</td><td>string<br><sub><mark style="color:$info;">Default: "code"</mark></sub></td><td><p>Define o campo e a direção a usar na pesquisa de registos. </p><p></p><p>Campos ordenáveis:</p><ul><li><code>id</code>, <code>code</code>, <code>external_code</code>, <code>fiscal_number</code>, <code>customer_name</code></li></ul><p>Use '-' antes do nome para ordem decrescente.</p></td></tr><tr><td>search</td><td>string</td><td><p>Define o termo de pesquisa a utilizar na lista de registos. </p><p></p><p>Campos Pesquisados:</p><ul><li><code>code</code>, <code>external_code</code>, <code>customer_name</code>, <code>commercial_name</code>, <code>fiscal_number</code>, etc.</li></ul></td></tr><tr><td>code</td><td>integer</td><td>Código do Cliente</td></tr><tr><td>customer_name</td><td>string</td><td><p>Nome do Cliente</p><p></p><p>Sufixos disponíveis:</p><ul><li><code>__search</code>: para pesquisa parcial</li></ul></td></tr><tr><td>commercial_name</td><td>string</td><td><p>Nome do Cliente</p><p></p><p>Sufixos disponíveis:</p><ul><li><code>__search</code>: para pesquisa parcial</li></ul></td></tr><tr><td>fiscal_number</td><td>String</td><td><p>Nº de Contribuinte</p><p></p><p>Sufixos disponíveis:</p><ul><li><code>__search</code>: para pesquisa parcial</li></ul></td></tr><tr><td>external_code</td><td>string</td><td>Código Alternativo do Cliente</td></tr></tbody></table>

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/customers/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "limit": 10,
    "offset": 0,
    "count": 120,
    "next": "https://api.cloudinvoice.net/customers/?limit=10&offset=10",
    "previous": null,
    "results":[
        {
            "id": 1,
            "code": 1,
            "external_code": "",
            "customer_name": "Consumidor Final",
            "commercial_name": "",
            "fiscal_number": "999999990",
            "street1": "",
            "street2": "",
            "zip_code": "",
            "zip_locale": "",
            "phone1": "",
            "mobile1": "",
            "email1": "",
            "total_debits": 168997.96,
            "total_credits": 135722.87,
            "current_balance": 33275.09,
            "fiscal_country_id": 1,
            "fiscal_country":{"code": "PT", "country_name": "Portugal"},
            "fiscal_status_type_id": 1592,
            "country_id": 1,
            "country":{"code": "PT", "country_name": "Portugal"},
            "fiscal_status_type":{"code": "1", "description": "Consumidor final"}
        },
        ...
    ]
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)

{% hint style="info" %}
**Notas:** Alguns dos campos do termo de pesquisa geral poderão ser incluídos mediante critérios específicos (Ex: Descrição será incluída na pesquisa geral apenas se o termo de pesquisa contiver 3 ou mais caracteres). Por defeito, o comportamento expectável será obter-se todos os items cujo o texto a pesquisar (search) esteja CONTIDO em pelo menos um dos campos incluídos na pesquisa geral.
{% endhint %}


# Create

Cria um novo cliente.

## Criar Cliente

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/customers/new/`

#### Request Body

<table data-search="false"><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>code</td><td>integer</td><td><p>Código do Cliente</p><p>Valor Único</p></td></tr><tr><td>customer_name<mark style="color:red;">*</mark></td><td>string</td><td>Nome do Cliente</td></tr><tr><td>fiscal_number</td><td>string</td><td>Contribuinte</td></tr><tr><td>commercial_name</td><td>string</td><td>Nome Comercial do Cliente</td></tr><tr><td>fiscal_status_type_id</td><td>integer</td><td><p>Tipo de Contribuinte</p><p></p><p>Consulte a tabela <a href="/documentacao-api/apendice#tipo-de-sujeito-campo-fiscal_status_type">Apêndice</a>.</p></td></tr><tr><td>fiscal_country_id</td><td>integer</td><td><p>País Fiscal</p><p></p><p>Consulte a tabela <a href="/documentacao-api/paises/list#lista-de-paises">Países</a>.</p></td></tr><tr><td>price_line_id</td><td>integer</td><td><p>Linha de Preços</p><p></p><p>Consulte a tabela <a href="/documentacao-api/linhas-de-precos/list#lista-de-linhas-de-precos">Linhas de Preços</a>.</p></td></tr><tr><td>payment_term_id</td><td>integer</td><td><p>Condições de Pagamento<br></p><p>Consulte a tabela <a href="/documentacao-api/condicoes-de-pagamento/list">Condições de Pagamento</a>.</p></td></tr><tr><td>payment_method_id</td><td>integer</td><td><p>Método de Pagamento</p><p></p><p>Consulte a tabela <a href="/documentacao-api/metodos-de-pagamento/list">Métodos de Pagamento</a>.</p></td></tr><tr><td>global_discount1</td><td>float</td><td>Desconto Global</td></tr><tr><td>line_discount1</td><td>float</td><td>Desconto de Linha 1</td></tr><tr><td>line_discount2</td><td>float</td><td>Desconto de Linha 2</td></tr><tr><td>line_discount3</td><td>float</td><td>Desconto de Linha 3</td></tr><tr><td>is_vat_exempt</td><td>boolean</td><td>Isento de IVA</td></tr><tr><td>vat_exempt_tax_exemption_id</td><td>integer</td><td>Tipo de Isenção</td></tr><tr><td>contact1</td><td>string</td><td>Nome do Contacto Principal</td></tr><tr><td>job_title1</td><td>string</td><td>Cargo do Contacto Principal</td></tr><tr><td>email1</td><td>email</td><td>E-mail do Contacto Principal</td></tr><tr><td>mobile1</td><td>string</td><td>Telemóvel do Contacto Principal</td></tr><tr><td>phone1</td><td>string</td><td>Telefone do Contacto Principal</td></tr><tr><td>fax1</td><td>string</td><td>Fax do Contacto Principal</td></tr><tr><td>web_address</td><td>string</td><td>Endereço da Entidade/Cliente</td></tr><tr><td>country_id</td><td>integer</td><td><p>País</p><p></p><p>Consulte a tabela <a href="/documentacao-api/paises/list#lista-de-paises">Países</a>.</p></td></tr><tr><td>district_id</td><td>integer</td><td><p>Distrito</p><p></p><p>Consulte a tabela <a href="/documentacao-api/distritos/list">Distritos</a>.</p></td></tr><tr><td>locality_id</td><td>integer</td><td><p>Concelho</p><p></p><p>Consulte a tabela <a href="/documentacao-api/concelhos/list">Concelhos</a>.</p></td></tr><tr><td>city</td><td>string</td><td>Cidade</td></tr><tr><td>street1</td><td>string</td><td>Morada Linha 1</td></tr><tr><td>street2</td><td>string</td><td>Morada Linha 2</td></tr><tr><td>zip_code</td><td>string</td><td>Código Postal</td></tr><tr><td>zip_locale</td><td>string</td><td>Localidade</td></tr><tr><td>external_code</td><td>string</td><td>Código Alternativo do Cliente</td></tr></tbody></table>

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/customers/new/
    -d '{
        "code": "1",
        "customer_name": "Cliente Demo",
        "fiscal_number": "999999990"
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "code": 1,
    "external_code": "",
    "customer_name": "Cliente Demo",
    "commercial_name": "",
    "fiscal_number": "999999990",
    "street1": "",
    "street2": "",
    "zip_code": "",
    "zip_locale": "",
    "city": "",
    "contact1": "",
    "job_title1": "",
    "phone1": "",
    "email1": "",
    "mobile1": "",
    "fax1": "",
    "web_address": "",
    "is_vat_exempt": false,
    "global_discount1": 0.0,
    "line_discount1": 0.0,
    "line_discount2": 0.0,
    "line_discount3": 0.0,
    "total_debits": 0.0,
    "total_credits": 0.0,
    "current_balance": 0.0,
    "party_class_id": 1601,
    "fiscal_country_id": 1,
    "fiscal_country": {
        "code": "PT",
        "country_name": "Portugal"
    },
    "country_id": 1,
    "country": {
        "code": "PT",
        "country_name": "Portugal"
    },
    "district_id": null,
    "district": null,
    "locality_id": null,
    "locality": null,
    "tax_region_id": 1,
    "tax_region": {
        "code": "PT",
        "description": "Continente"
    },
    "tax_zone_id": 21,
    "currency_id": 1,
    "currency": {
        "code": "EUR",
        "description": "Euros"
    },
    "fiscal_status_type_id": 1592,
    "vat_exempt_tax_exemption_id": null,
    "vat_exempt_tax_exemption": null,
    "payment_term_id": null,
    "payment_term": null,
    "payment_method_id": null,
    "payment_method": null,
    "price_line_id": null,
    "price_line": null,
    "party_class": {
        "code": "C",
        "description": "Cliente"
    },
    "fiscal_status_type": {
        "code": "1",
        "description": "Consumidor final"
    },
    "tax_zone": {
        "code": "N",
        "description": "Mercado Nacional"
    }
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Get

Obtém detalhes do cliente.

## Obter Cliente

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/customers/:id/`

#### Path Parameters

| Name                                 | Type    | Description     |
| ------------------------------------ | ------- | --------------- |
| id<mark style="color:red;">\*</mark> | integer | O ID do Cliente |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/customers/1/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "code": 1,
    "external_code": "",
    "customer_name": "Cliente Demo",
    "commercial_name": "",
    "fiscal_number": "999999990",
    "street1": "",
    "street2": "",
    "zip_code": "",
    "zip_locale": "",
    "city": "",
    "contact1": "",
    "job_title1": "",
    "phone1": "",
    "email1": "",
    "mobile1": "",
    "fax1": "",
    "web_address": "",
    "is_vat_exempt": false,
    "global_discount1": 0.0,
    "line_discount1": 0.0,
    "line_discount2": 0.0,
    "line_discount3": 0.0,
    "total_debits": 0.0,
    "total_credits": 0.0,
    "current_balance": 0.0,
    "party_class_id": 1601,
    "fiscal_country_id": 1,
    "fiscal_country": {
        "code": "PT",
        "country_name": "Portugal"
    },
    "country_id": 1,
    "country": {
        "code": "PT",
        "country_name": "Portugal"
    },
    "district_id": null,
    "district": null,
    "locality_id": null,
    "locality": null,
    "tax_region_id": 1,
    "tax_region": {
        "code": "PT",
        "description": "Continente"
    },
    "tax_zone_id": 21,
    "currency_id": 1,
    "currency": {
        "code": "EUR",
        "description": "Euros"
    },
    "fiscal_status_type_id": 1592,
    "vat_exempt_tax_exemption_id": null,
    "vat_exempt_tax_exemption": null,
    "payment_term_id": null,
    "payment_term": null,
    "payment_method_id": null,
    "payment_method": null,
    "price_line_id": null,
    "price_line": null,
    "party_class": {
        "code": "C",
        "description": "Cliente"
    },
    "fiscal_status_type": {
        "code": "1",
        "description": "Consumidor final"
    },
    "tax_zone": {
        "code": "N",
        "description": "Mercado Nacional"
    }
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Seek

Procura por cliente a partir do seu código ou número de contribuinte.

## Procurar Cliente

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/customers/seek/:search/`

#### Path Parameters

| Name                                     | Type   | Description                                                                 |
| ---------------------------------------- | ------ | --------------------------------------------------------------------------- |
| search<mark style="color:red;">\*</mark> | string | Código, Número de Contribuinte ou Código Alternativo do Cliente a procurar. |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/customers/seek/999999990/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "code": 1,
    "external_code": "",
    "customer_name": "Cliente Demo",
    "commercial_name": "",
    "fiscal_number": "999999990",
    "street1": "",
    "street2": "",
    "zip_code": "",
    "zip_locale": "",
    "city": "",
    "contact1": "",
    "job_title1": "",
    "phone1": "",
    "email1": "",
    "mobile1": "",
    "fax1": "",
    "web_address": "",
    "is_vat_exempt": false,
    "global_discount1": 0.0,
    "line_discount1": 0.0,
    "line_discount2": 0.0,
    "line_discount3": 0.0,
    "total_debits": 0.0,
    "total_credits": 0.0,
    "current_balance": 0.0,
    "party_class_id": 1601,
    "fiscal_country_id": 1,
    "fiscal_country": {
        "code": "PT",
        "country_name": "Portugal"
    },
    "country_id": 1,
    "country": {
        "code": "PT",
        "country_name": "Portugal"
    },
    "district_id": null,
    "district": null,
    "locality_id": null,
    "locality": null,
    "tax_region_id": 1,
    "tax_region": {
        "code": "PT",
        "description": "Continente"
    },
    "tax_zone_id": 21,
    "currency_id": 1,
    "currency": {
        "code": "EUR",
        "description": "Euros"
    },
    "fiscal_status_type_id": 1592,
    "vat_exempt_tax_exemption_id": null,
    "vat_exempt_tax_exemption": null,
    "payment_term_id": null,
    "payment_term": null,
    "payment_method_id": null,
    "payment_method": null,
    "price_line_id": null,
    "price_line": null,
    "party_class": {
        "code": "C",
        "description": "Cliente"
    },
    "fiscal_status_type": {
        "code": "1",
        "description": "Consumidor final"
    },
    "tax_zone": {
        "code": "N",
        "description": "Mercado Nacional"
    }
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Exists

Indica, caso exista, o ID do cliente a partir do seu código ou número de contribuinte.

## Verificar Existência de Cliente

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/customers/exists/:search/`

#### Path Parameters

| Name                                     | Type   | Description                                                                 |
| ---------------------------------------- | ------ | --------------------------------------------------------------------------- |
| search<mark style="color:red;">\*</mark> | string | Código, Número de Contribuinte ou Código Alternativo do Cliente a procurar. |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/customers/exists/1/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "exists": true,
    "id": 1,
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Update

Altera dados de um cliente.

## Alterar Cliente

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/customers/:id/update/`

#### Request Body

<table data-search="false"><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>code</td><td>integer</td><td><p>Código do Cliente</p><p>Valor Único</p></td></tr><tr><td>customer_name<mark style="color:red;">*</mark></td><td>string</td><td>Nome do Cliente</td></tr><tr><td>fiscal_number</td><td>string</td><td>Contribuinte</td></tr><tr><td>commercial_name</td><td>string</td><td>Nome Comercial do Cliente</td></tr><tr><td>fiscal_status_type_id</td><td>integer</td><td><p>Tipo de Contribuinte</p><p></p><p>Consulte a tabela <a href="/documentacao-api/apendice#tipo-de-sujeito-campo-fiscal_status_type">Apêndice</a>.</p></td></tr><tr><td>fiscal_country_id</td><td>integer</td><td><p>País Fiscal</p><p></p><p>Consulte a tabela <a href="/documentacao-api/paises/list#lista-de-paises">Países</a>.</p></td></tr><tr><td>price_line_id</td><td>integer</td><td><p>Linha de Preços</p><p></p><p>Consulte a tabela <a href="/documentacao-api/linhas-de-precos/list#lista-de-linhas-de-precos">Linhas de Preços</a>.</p></td></tr><tr><td>payment_method_id</td><td>String</td><td><p>Método de Pagamento</p><p></p><p>Consulte a tabela <a href="/documentacao-api/metodos-de-pagamento/list">Métodos de Pagamento</a>.</p></td></tr><tr><td>global_discount1</td><td>float</td><td>Desconto Global</td></tr><tr><td>line_discount1</td><td>float</td><td>Desconto de Linha 1</td></tr><tr><td>line_discount2</td><td>float</td><td>Desconto de Linha 2</td></tr><tr><td>line_discount3</td><td>float</td><td>Desconto de Linha 3</td></tr><tr><td>is_vat_exempt</td><td>boolean</td><td>Isento de IVA</td></tr><tr><td>vat_exempt_tax_exemption_id</td><td>integer</td><td>Tipo de Isenção</td></tr><tr><td>contact1</td><td>string</td><td>Nome do Contacto Principal</td></tr><tr><td>job_title1</td><td>string</td><td>Cargo do Contacto Principal</td></tr><tr><td>email1</td><td>email</td><td>E-mail do Contacto Principal</td></tr><tr><td>mobile1</td><td>string</td><td>Telemóvel do Contacto Principal</td></tr><tr><td>phone1</td><td>string</td><td>Telefone do Contacto Principal</td></tr><tr><td>fax1</td><td>string</td><td>Fax do Contacto Principal</td></tr><tr><td>web_address</td><td>string</td><td>Endereço da Entidade/Cliente</td></tr><tr><td>country_id</td><td>integer</td><td><p>País</p><p></p><p>Consulte a tabela <a href="/documentacao-api/paises/list#lista-de-paises">Países</a>.</p></td></tr><tr><td>district_id</td><td>integer</td><td><p>Distrito</p><p></p><p>Consulte a tabela <a href="/documentacao-api/distritos/list">Distritos</a>.</p></td></tr><tr><td>locality_id</td><td>integer</td><td><p>Concelho</p><p></p><p>Consulte a tabela <a href="/documentacao-api/concelhos/list">Concelhos</a>.</p></td></tr><tr><td>city</td><td>string</td><td>Cidade</td></tr><tr><td>street1</td><td>string</td><td>Morada Linha 1</td></tr><tr><td>street2</td><td>string</td><td>Morada Linha 2</td></tr><tr><td>zip_code</td><td>string</td><td>Código Postal</td></tr><tr><td>zip_locale</td><td>string</td><td>Localidade</td></tr><tr><td>external_code</td><td>string</td><td>Código Alternativo do Cliente</td></tr></tbody></table>

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/customers/1/update/
    -d '{
        "customer_name": "Cliente Demo - Update"
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "code": 1,
    "external_code": "",
    "customer_name": "Cliente Demo - Update",
    "commercial_name": "",
    "fiscal_number": "999999990",
    "street1": "",
    "street2": "",
    "zip_code": "",
    "zip_locale": "",
    "city": "",
    "contact1": "",
    "job_title1": "",
    "phone1": "",
    "email1": "",
    "mobile1": "",
    "fax1": "",
    "web_address": "",
    "is_vat_exempt": false,
    "global_discount1": 0.0,
    "line_discount1": 0.0,
    "line_discount2": 0.0,
    "line_discount3": 0.0,
    "total_debits": 0.0,
    "total_credits": 0.0,
    "current_balance": 0.0,
    "party_class_id": 1601,
    "fiscal_country_id": 1,
    "fiscal_country": {
        "code": "PT",
        "country_name": "Portugal"
    },
    "country_id": 1,
    "country": {
        "code": "PT",
        "country_name": "Portugal"
    },
    "district_id": null,
    "district": null,
    "locality_id": null,
    "locality": null,
    "tax_region_id": 1,
    "tax_region": {
        "code": "PT",
        "description": "Continente"
    },
    "tax_zone_id": 21,
    "currency_id": 1,
    "currency": {
        "code": "EUR",
        "description": "Euros"
    },
    "fiscal_status_type_id": 1592,
    "vat_exempt_tax_exemption_id": null,
    "vat_exempt_tax_exemption": null,
    "payment_term_id": null,
    "payment_term": null,
    "payment_method_id": null,
    "payment_method": null,
    "price_line_id": null,
    "price_line": null,
    "party_class": {
        "code": "C",
        "description": "Cliente"
    },
    "fiscal_status_type": {
        "code": "1",
        "description": "Consumidor final"
    },
    "tax_zone": {
        "code": "N",
        "description": "Mercado Nacional"
    }
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Delete

Apaga um cliente.

## Apagar Cliente

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/customers/:id/delete/`

#### Path Parameters

| Name                                 | Type    | Description   |
| ------------------------------------ | ------- | ------------- |
| id<mark style="color:red;">\*</mark> | integer | ID do Cliente |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/customers/1/delete/
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Mov. Conta-Corrente

Permite a visualização, criação e remoção de Movimentos de Conta-Corrente do Cliente.


# List

Fornece uma lista de movimentos de conta-corrente do cliente.

## Listar Movimentos de Conta-Corrente do Cliente

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/customers/:cust_id/movements/`

#### Path Parameters

| Name     | Type    | Description   |
| -------- | ------- | ------------- |
| cust\_id | integer | ID do Cliente |

#### Query Parameters

<table data-search="false"><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>limit</td><td>integer</td><td>Define o número de registos por pesquisa.</td></tr><tr><td>offset</td><td>integer</td><td><p>Indica a posição inicial da pesquisa.</p><p>Retorna a lista de registos compreendida entre <code>offset</code> e <code>offset+limit</code>.</p></td></tr><tr><td>document_header</td><td>integer</td><td>ID do Documento</td></tr><tr><td>document_reference</td><td>string</td><td><p>Referência do Documento</p><p></p><p>Sufixos disponíveis:</p><ul><li><code>__search</code>: para pesquisa parcial</li></ul></td></tr><tr><td>account_movement_type</td><td>integer</td><td>Tipo de Movimento<br><br>Consulte a tabela <a href="/documentacao-api/apendice#tipos-de-movimentos-de-conta-corrente-credito-ou-debito-campo-account_movement_type">Apêndice</a>.</td></tr><tr><td>is_automatic_entry</td><td>boolean</td><td>Movimento Gerado Automaticamente</td></tr><tr><td>is_movement_reconciled</td><td>boolean</td><td>Movimento Conciliado</td></tr></tbody></table>

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/customers/2/movements/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "limit": 10,
    "offset": 0,
    "count": 8,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "document_header_id": 1,
            "description": "Factura",
            "document_reference": "FAC A01/1",
            "party_id": 2,
            "movement_date": "2026-07-03",
            "movement_amount": 1.23,
            "due_date": "2026-07-03",
            "due_amount": 1.23,
            "is_automatic_entry": true,
            "is_movement_reconciled": false,
            "document_nature_id": 301,
            "document_nature": {
                "code": "FT",
                "description": "Factura"
            },
            "account_movement_type_id": 1753,
            "account_movement_type": {
                "code": "D",
                "description": "Débito"
            }
        },
        ...
    ]
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)

{% hint style="info" %}
**Notas:** Alguns dos campos do termo de pesquisa geral poderão ser incluídos mediante critérios específicos (Ex: Descrição será incluída na pesquisa geral apenas se o termo de pesquisa contiver 3 ou mais caracteres). Por defeito, o comportamento expectável será obter-se todos os items cujo o texto a pesquisar (search) esteja CONTIDO em pelo menos um dos campos incluídos na pesquisa geral.
{% endhint %}


# Create

Cria movimento de conta-corrente manual.

## Criar Movimento de Conta-Corrente

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/customers/:cust_id/movements/new/`

#### Path Parameters

| Name     | Type    | Description   |
| -------- | ------- | ------------- |
| cust\_id | integer | ID do Cliente |

#### Request Body

<table data-search="false"><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>description<mark style="color:red;">*</mark></td><td>string</td><td>Descrição do Movimento</td></tr><tr><td>document_nature_id<mark style="color:red;">*</mark></td><td>integer</td><td><p>Natureza do Documento</p><p></p><p>Consulte a tabela <a href="/documentacao-api/apendice#naturezas-de-documentos-campo-document_nature">Apêndice</a>.</p></td></tr><tr><td>document_reference<mark style="color:red;">*</mark></td><td>string</td><td><p>Referência do Documento<br><br>Identificador único do documento original que gerou o movimento.<br></p><p><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> É imperativo que o valor fornecido esteja em conformidade com identificadores já anteriormente comunicados à AT, para que seja estabelecida a relação.</p></td></tr><tr><td>document_reference_date</td><td>date<br><sub><mark style="color:$info;">Format: yyyy-mm-dd</mark></sub></td><td>Data do Documento de Referência</td></tr><tr><td>movement_amount<mark style="color:red;">*</mark></td><td>float</td><td>Total do Movimento<br><br>O movimento será considerado a Débito se o valor fornecido for positivo, ou a Crédito se for negativo. Valores nulos geram erro na importação dos dados.</td></tr><tr><td>due_date<mark style="color:red;">*</mark></td><td>date<br><sub><mark style="color:$info;">Format: yyyy-mm-dd</mark></sub></td><td>Data de Vencimento</td></tr><tr><td>due_amount</td><td>float<br><sub><mark style="color:$info;">Default: 0</mark></sub></td><td><p>Valor Pendente</p><p><br>Se o valor fornecido for diferente do fornecido em 'movement_amount' (em valor absoluto), o movimento será criado como parcialmente saldado.</p></td></tr></tbody></table>

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/customers/2/movements/new/
    -d '{
        "description": "Factura",
        "document_nature_id": 301,
        "document_reference": "FAC Z01/1",
        "movement_amount": 10,
        "due_date": "2017-05-20",
        "due_amount": 10
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "description": "Factura",
    "document_reference": "FAC Z01/1",
    "document_nature_id": 301,
    "document_nature": {
        "code": "FT",
        "description": "Factura"
    },
    "account_movement_type_id": 1753,
    "account_movement_type": {
        "code": "D",
        "description": "Débito"
    },
    "account_type_id": 1,
    "account_type": {
        "code": "CC",
        "description": "Conta-corrente"
    },
    "party_class_id": 1601,
    "party_class": {
        "code": "C",
        "description": "Cliente"
    },
    "party_id": 2,
    "movement_date": "2026-08-18",
    "movement_time": null,
    "movement_amount": 10.0,
    "credit_amount": 0.0,
    "debit_amount": 10.0,
    "due_date": "2017-05-20",
    "due_amount": 10.0,
    "withholding_amount": 0.0,
    "withholding_due_amount": 0.0,
    "total_cumulate_amount": 0.0,
    "is_automatic_entry": false,
    "is_movement_reconciled": true,
    "is_cash_vat_scheme": false,
    "used_in_receipt": false,
    "used_in_receipt_ric": false
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Get

Obtém detalhes do movimento de conta-corrente do cliente.

## Obter Movimento de Conta-Corrente

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/customers/:cust_id/movements/:id/`

#### Path Parameters

| Name     | Type    | Description     |
| -------- | ------- | --------------- |
| cust\_id | integer | ID do Cliente   |
| id       | integer | ID do Movimento |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/customers/2/movements/1/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "document_header_id": 1,
    "description": "Factura",
    "document_reference": "FAC A01/1",
    "document_code": "FAC",
    "document_nature_id": 301,
    "document_nature": {
        "code": "FT",
        "description": "Factura"
    },
    "account_movement_type_id": 1753,
    "account_movement_type": {
        "code": "D",
        "description": "Débito"
    },
    "account_type_id": 1,
    "account_type": {
        "code": "CC",
        "description": "Conta-corrente"
    },
    "party_class_id": 1601,
    "party_class": {
        "code": "C",
        "description": "Cliente"
    },
    "party_id": 2,
    "movement_date": "2026-07-03",
    "movement_time": "18:27:31",
    "movement_amount": 1.23,
    "credit_amount": 0.0,
    "debit_amount": 1.23,
    "due_date": "2026-07-03",
    "due_amount": 1.23,
    "withholding_amount": 0.0,
    "withholding_due_amount": 0.0,
    "total_cumulate_amount": 1.23,
    "is_automatic_entry": true,
    "is_movement_reconciled": false,
    "is_cash_vat_scheme": false,
    "used_in_receipt": true,
    "used_in_receipt_ric": false
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Delete

Apaga movimento de conta-corrente manual.

## Apagar Movimento de Conta-Corrente

{% hint style="danger" %}
Apenas poderão ser apagados Movimentos de Conta-Corrente que tenham sido criados manualmente.
{% endhint %}

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/customers/:cust_id/movements/:id/delete/`

#### Path Parameters

| Name     | Type    | Description     |
| -------- | ------- | --------------- |
| cust\_id | integer | ID do Cliente   |
| id       | integer | ID do Movimento |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/customers/2/movements/1/delete/
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Fornecedores

Um Fornecedor representa uma entidade, empresa ou pessoa. Os fornecedores são habitualmente utilizados em documentos de compra. Também podem ser geridas as contas-correntes e saldos de cada um.


# List

Fornece uma lista de todos os fornecedores existentes.

## Listar Fornecedores

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/suppliers/`

#### Query Parameters

| Name           | Type                                                                          | Description                                                                                                                                                                                                                                                          |
| -------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| limit          | integer                                                                       | Define o número de registos por pesquisa.                                                                                                                                                                                                                            |
| offset         | integer                                                                       | <p>Indica a posição inicial da pesquisa.</p><p>Retorna a lista de registos compreendida entre <code>offset</code> e <code>offset+limit</code>.</p>                                                                                                                   |
| ordering       | <p>string<br><sub><mark style="color:$info;">Default: "code"</mark></sub></p> | <p>Define o campo e a direção a usar na pesquisa de registos. </p><p></p><p>Campos ordenáveis:</p><ul><li><code>id</code>, <code>code</code>, <code>fiscal\_number</code>, <code>supplier\_name</code></li></ul><p>Use '-' antes do nome para ordem decrescente.</p> |
| search         | string                                                                        | <p>Define o termo de pesquisa a utilizar na lista de registos. </p><p></p><p>Campos Pesquisados:</p><ul><li><code>code</code>, <code>supplier\_name</code>, <code>fiscal\_number</code>, etc.</li></ul>                                                              |
| code           | integer                                                                       | Código do Fornecedor                                                                                                                                                                                                                                                 |
| supplier\_name | string                                                                        | <p>Nome do Fornecedor</p><p></p><p>Sufixos disponíveis:</p><ul><li><code>\_\_search</code>: para pesquisa parcial</li></ul>                                                                                                                                          |
| fiscal\_number | String                                                                        | <p>Contribuinte</p><p></p><p>Sufixos disponíveis:</p><ul><li><code>\_\_search</code>: para pesquisa parcial</li></ul>                                                                                                                                                |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/suppliers/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "limit": 10,
    "offset": 0,
    "count": 120,
    "next": "https://api.cloudinvoice.net/suppliers/?limit=10&offset=10",
    "previous": null,
    "results":[
        {
            "id": 1,
            "code": 1,
            "supplier_name": "Fornecedor 1",
            "fiscal_number": "500000000",
            "fiscal_country_id": 1,
            "fiscal_country": {"code": "PT", "country_name": "Portugal"},
            "fiscal_status_type_id": 1593,
            "fiscal_status_type": {"code": "2", "description": "Sujeito Passivo de IVA"},
            "street1": "",
            "street2": "",
            "zip_code": "",
            "zip_locale": "",
            "country_id": 1,
            "country": {"code": "PT", "country_name": "Portugal"},
            "phone1": "",
            "mobile1": "",
            "email1": "",
            "total_debits": 0.0,
            "total_credits": 100.0,
            "current_balance": 100.0
        },
        ...
    ]
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)

{% hint style="info" %}
**Notas:** Alguns dos campos do termo de pesquisa geral poderão ser incluídos mediante critérios específicos (Ex: Descrição será incluída na pesquisa geral apenas se o termo de pesquisa contiver 3 ou mais caracteres). Por defeito, o comportamento expectável será obter-se todos os items cujo o texto a pesquisar (search) esteja CONTIDO em pelo menos um dos campos incluídos na pesquisa geral.
{% endhint %}


# Create

Cria um novo fornecedor.

## Criar Fornecedor

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/suppliers/new/`

#### Request Body

| Name                                             | Type    | Description                                                                                                                                            |
| ------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| code                                             | integer | <p>Código do Cliente<br>Valor Único</p>                                                                                                                |
| supplier\_name<mark style="color:red;">\*</mark> | string  | Nome do Fornecedor                                                                                                                                     |
| fiscal\_number                                   | string  | Contribuinte                                                                                                                                           |
| fiscal\_status\_type\_id                         | integer | <p>Tipo de Contribuinte</p><p></p><p>Consulte a tabela <a href="/documentacao-api/apendice#tipo-de-sujeito-campo-fiscal_status_type">Apêndice</a>.</p> |
| fiscal\_country\_id                              | integer | <p>País Fiscal</p><p></p><p>Consulte a tabela <a href="/documentacao-api/paises/list#lista-de-paises">Países</a>.</p>                                  |
| payment\_term\_id                                | integer | <p>Condições de Pagamento<br></p><p>Consulte a tabela <a href="/documentacao-api/condicoes-de-pagamento/list">Condições de Pagamento</a>.</p>          |
| payment\_method\_id                              | integer | <p>Método de Pagamento</p><p></p><p>Consulte a tabela <a href="/documentacao-api/metodos-de-pagamento/list">Métodos de Pagamento</a>.</p>              |
| is\_vat\_exempt                                  | boolean | Isento de IVA                                                                                                                                          |
| vat\_exempt\_tax\_exemption\_id                  | integer | Tipo de Isenção                                                                                                                                        |
| contact1                                         | string  | Nome do Contacto Principal                                                                                                                             |
| job\_title1                                      | string  | Cargo do Contacto Principal                                                                                                                            |
| email1                                           | email   | E-mail do Contacto Principal                                                                                                                           |
| mobile1                                          | string  | Telemóvel do Contacto Principal                                                                                                                        |
| phone1                                           | string  | Telefone do Contacto Principal                                                                                                                         |
| fax1                                             | string  | Fax do Contacto Principal                                                                                                                              |
| web\_address                                     | string  | Endereço da Entidade/Cliente                                                                                                                           |
| country\_id                                      | integer | <p>País</p><p></p><p>Consulte a tabela <a href="/documentacao-api/paises/list#lista-de-paises">Países</a>.</p>                                         |
| district\_id                                     | integer | <p>Distrito</p><p></p><p>Consulte a tabela <a href="/documentacao-api/distritos/list">Distritos</a>.</p>                                               |
| locality\_id                                     | integer | <p>Concelho</p><p></p><p>Consulte a tabela <a href="/documentacao-api/concelhos/list">Concelhos</a>.</p>                                               |
| city                                             | string  | Cidade                                                                                                                                                 |
| street1                                          | string  | Morada Linha 1                                                                                                                                         |
| street2                                          | string  | Morada Linha 2                                                                                                                                         |
| zip\_code                                        | string  | Código Postal                                                                                                                                          |
| zip\_locale                                      | string  | Localidade                                                                                                                                             |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/suppliers/new/
    -d '{
        "code": "1",
        "supplier_name": "Fornecedor Demo",
        "fiscal_number": "500000000"
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
  "id": 1,
  "code": 1,
  "supplier_name": "Fornecedor Demo",
  "party_class_id": 1602,
  "party_class": {
    "code": "F",
    "description": "Fornecedor"
  },
  "fiscal_number": "500000000",
  "fiscal_country_id": 1,
  "fiscal_country": {
    "code": "PT",
    "country_name": "Portugal"
  },
  "fiscal_status_type_id": 1593,
  "fiscal_status_type": {
    "code": "2",
    "description": "Sujeito Passivo de IVA"
  },
  "tax_region_id": 1,
  "tax_region": {
    "code": "PT",
    "description": "Continente"
  },
  "tax_zone_id": 21,
  "tax_zone": {
    "code": "N",
    "description": "Mercado Nacional"
  },
  "is_vat_exempt": false,
  "vat_exempt_tax_exemption_id": null,
  "vat_exempt_tax_exemption": null,
  "street1": "",
  "street2": "",
  "zip_code": "",
  "zip_locale": "",
  "city": "",
  "country_id": 1,
  "country": {
    "code": "PT",
    "country_name": "Portugal"
  },
  "district_id": null,
  "district": null,
  "locality_id": null,
  "locality": null,
  "contact1": "",
  "job_title1": "",
  "phone1": "",
  "email1": "",
  "mobile1": "",
  "fax1": "",
  "web_address": "",
  "payment_term_id": null,
  "payment_term": null,
  "payment_method_id": null,
  "payment_method": null
  "currency_id": 1,
  "currency": {
    "code": "EUR",
    "description": "Euros"
  },
  "total_debits": 0.0,
  "total_credits": 0.0,
  "current_balance": 0.0
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Get

Obtém detalhes do fornecedor.

## Obter Fornecedor

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/suppliers/:id/`

#### Path Parameters

| Name                                 | Type    | Description        |
| ------------------------------------ | ------- | ------------------ |
| id<mark style="color:red;">\*</mark> | integer | O ID do Fornecedor |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/suppliers/1/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
  "id": 1,
  "code": 1,
  "supplier_name": "Fornecedor Demo",
  "party_class_id": 1602,
  "party_class": {
    "code": "F",
    "description": "Fornecedor"
  },
  "fiscal_number": "500000000",
  "fiscal_country_id": 1,
  "fiscal_country": {
    "code": "PT",
    "country_name": "Portugal"
  },
  "fiscal_status_type_id": 1593,
  "fiscal_status_type": {
    "code": "2",
    "description": "Sujeito Passivo de IVA"
  },
  "tax_region_id": 1,
  "tax_region": {
    "code": "PT",
    "description": "Continente"
  },
  "tax_zone_id": 21,
  "tax_zone": {
    "code": "N",
    "description": "Mercado Nacional"
  },
  "is_vat_exempt": false,
  "vat_exempt_tax_exemption_id": null,
  "vat_exempt_tax_exemption": null,
  "street1": "",
  "street2": "",
  "zip_code": "",
  "zip_locale": "",
  "city": "",
  "country_id": 1,
  "country": {
    "code": "PT",
    "country_name": "Portugal"
  },
  "district_id": null,
  "district": null,
  "locality_id": null,
  "locality": null,
  "contact1": "",
  "job_title1": "",
  "phone1": "",
  "email1": "",
  "mobile1": "",
  "fax1": "",
  "web_address": "",
  "payment_term_id": null,
  "payment_term": null,
  "payment_method_id": null,
  "payment_method": null
  "currency_id": 1,
  "currency": {
    "code": "EUR",
    "description": "Euros"
  },
  "total_debits": 0.0,
  "total_credits": 0.0,
  "current_balance": 0.0
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Seek

Procura por fornecedor a partir do seu código ou número de contribuinte.

## Procurar Fornecedor

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/suppliers/seek/:search/`

#### Path Parameters

| Name                                     | Type   | Description                                   |
| ---------------------------------------- | ------ | --------------------------------------------- |
| search<mark style="color:red;">\*</mark> | string | Código/Contribuinte do Fornecedor a procurar. |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/suppliers/seek/500000000/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
  "id": 1,
  "code": 1,
  "supplier_name": "Fornecedor Demo",
  "party_class_id": 1602,
  "party_class": {
    "code": "F",
    "description": "Fornecedor"
  },
  "fiscal_number": "500000000",
  "fiscal_country_id": 1,
  "fiscal_country": {
    "code": "PT",
    "country_name": "Portugal"
  },
  "fiscal_status_type_id": 1593,
  "fiscal_status_type": {
    "code": "2",
    "description": "Sujeito Passivo de IVA"
  },
  "tax_region_id": 1,
  "tax_region": {
    "code": "PT",
    "description": "Continente"
  },
  "tax_zone_id": 21,
  "tax_zone": {
    "code": "N",
    "description": "Mercado Nacional"
  },
  "is_vat_exempt": false,
  "vat_exempt_tax_exemption_id": null,
  "vat_exempt_tax_exemption": null,
  "street1": "",
  "street2": "",
  "zip_code": "",
  "zip_locale": "",
  "city": "",
  "country_id": 1,
  "country": {
    "code": "PT",
    "country_name": "Portugal"
  },
  "district_id": null,
  "district": null,
  "locality_id": null,
  "locality": null,
  "contact1": "",
  "job_title1": "",
  "phone1": "",
  "email1": "",
  "mobile1": "",
  "fax1": "",
  "web_address": "",
  "payment_term_id": null,
  "payment_term": null,
  "payment_method_id": null,
  "payment_method": null
  "currency_id": 1,
  "currency": {
    "code": "EUR",
    "description": "Euros"
  },
  "total_debits": 0.0,
  "total_credits": 0.0,
  "current_balance": 0.0
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Exists

Indica, caso exista, o ID do fornecedor a partir do seu código ou número de contribuinte.

## Verificar Existência de Fornecedor

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/suppliers/exists/:search/`

#### Path Parameters

| Name                                     | Type   | Description                                   |
| ---------------------------------------- | ------ | --------------------------------------------- |
| search<mark style="color:red;">\*</mark> | string | Código/Contribuinte do Fornecedor a procurar. |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/suppliers/exists/1/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "exists": true,
    "id": 1,
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Update

Altera dados de um fornecedor.

## Alterar Fornecedor

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/suppliers/:id/update/`

#### Request Body

| Name                                             | Type    | Description                                                                                                                                            |
| ------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| code                                             | integer | <p>Código do Cliente<br>Valor Único</p>                                                                                                                |
| supplier\_name<mark style="color:red;">\*</mark> | string  | Nome do Fornecedor                                                                                                                                     |
| fiscal\_number                                   | string  | Contribuinte                                                                                                                                           |
| fiscal\_status\_type\_id                         | integer | <p>Tipo de Contribuinte</p><p></p><p>Consulte a tabela <a href="/documentacao-api/apendice#tipo-de-sujeito-campo-fiscal_status_type">Apêndice</a>.</p> |
| fiscal\_country\_id                              | integer | <p>País Fiscal</p><p></p><p>Consulte a tabela <a href="/documentacao-api/paises/list#lista-de-paises">Países</a>.</p>                                  |
| payment\_term\_id                                | integer | <p>Condições de Pagamento<br></p><p>Consulte a tabela <a href="/documentacao-api/condicoes-de-pagamento/list">Condições de Pagamento</a>.</p>          |
| payment\_method\_id                              | integer | <p>Método de Pagamento</p><p></p><p>Consulte a tabela <a href="/documentacao-api/metodos-de-pagamento/list">Métodos de Pagamento</a>.</p>              |
| is\_vat\_exempt                                  | boolean | Isento de IVA                                                                                                                                          |
| vat\_exempt\_tax\_exemption\_id                  | integer | Tipo de Isenção                                                                                                                                        |
| contact1                                         | string  | Nome do Contacto Principal                                                                                                                             |
| job\_title1                                      | string  | Cargo do Contacto Principal                                                                                                                            |
| email1                                           | email   | E-mail do Contacto Principal                                                                                                                           |
| mobile1                                          | string  | Telemóvel do Contacto Principal                                                                                                                        |
| phone1                                           | string  | Telefone do Contacto Principal                                                                                                                         |
| fax1                                             | string  | Fax do Contacto Principal                                                                                                                              |
| web\_address                                     | string  | Endereço da Entidade/Cliente                                                                                                                           |
| country\_id                                      | integer | <p>País</p><p></p><p>Consulte a tabela <a href="/documentacao-api/paises/list#lista-de-paises">Países</a>.</p>                                         |
| district\_id                                     | integer | <p>Distrito</p><p></p><p>Consulte a tabela <a href="/documentacao-api/distritos/list">Distritos</a>.</p>                                               |
| locality\_id                                     | integer | <p>Concelho</p><p></p><p>Consulte a tabela <a href="/documentacao-api/concelhos/list">Concelhos</a>.</p>                                               |
| city                                             | string  | Cidade                                                                                                                                                 |
| street1                                          | string  | Morada Linha 1                                                                                                                                         |
| street2                                          | string  | Morada Linha 2                                                                                                                                         |
| zip\_code                                        | string  | Código Postal                                                                                                                                          |
| zip\_locale                                      | string  | Localidade                                                                                                                                             |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/suppliers/1/update/
    -d '{
        "supplier_name": "Fornecedor Demo - Update"
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
  "id": 1,
  "code": 1,
  "supplier_name": "Fornecedor Demo - Update",
  "party_class_id": 1602,
  "party_class": {
    "code": "F",
    "description": "Fornecedor"
  },
  "fiscal_number": "500000000",
  "fiscal_country_id": 1,
  "fiscal_country": {
    "code": "PT",
    "country_name": "Portugal"
  },
  "fiscal_status_type_id": 1593,
  "fiscal_status_type": {
    "code": "2",
    "description": "Sujeito Passivo de IVA"
  },
  "tax_region_id": 1,
  "tax_region": {
    "code": "PT",
    "description": "Continente"
  },
  "tax_zone_id": 21,
  "tax_zone": {
    "code": "N",
    "description": "Mercado Nacional"
  },
  "is_vat_exempt": false,
  "vat_exempt_tax_exemption_id": null,
  "vat_exempt_tax_exemption": null,
  "street1": "",
  "street2": "",
  "zip_code": "",
  "zip_locale": "",
  "city": "",
  "country_id": 1,
  "country": {
    "code": "PT",
    "country_name": "Portugal"
  },
  "district_id": null,
  "district": null,
  "locality_id": null,
  "locality": null,
  "contact1": "",
  "job_title1": "",
  "phone1": "",
  "email1": "",
  "mobile1": "",
  "fax1": "",
  "web_address": "",
  "payment_term_id": null,
  "payment_term": null,
  "payment_method_id": null,
  "payment_method": null
  "currency_id": 1,
  "currency": {
    "code": "EUR",
    "description": "Euros"
  },
  "total_debits": 0.0,
  "total_credits": 0.0,
  "current_balance": 0.0
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Delete

Apaga um fornecedor.

## Apagar Fornecedor

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/suppliers/:id/delete/`

#### Path Parameters

| Name                                 | Type    | Description      |
| ------------------------------------ | ------- | ---------------- |
| id<mark style="color:red;">\*</mark> | integer | ID do Fornecedor |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/suppliers/1/delete/
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Vendedores

Um Vendedor representa habitualmente um colaborador da Empresa. Permitem, entre outras coisas, efectuar uma gestão de Comissões.


# List

Fornece uma lista de todos os vendedores existentes.

## Listar Vendedores

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/salesmen/`

#### Query Parameters

| Name           | Type                                                                          | Description                                                                                                                                                                                                                             |
| -------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| limit          | integer                                                                       | Define o número de registos por pesquisa.                                                                                                                                                                                               |
| offset         | integer                                                                       | <p>Indica a posição inicial da pesquisa.</p><p>Retorna a lista de registos compreendida entre <code>offset</code> e <code>offset+limit</code>.</p>                                                                                      |
| ordering       | <p>string<br><sub><mark style="color:$info;">Default: "code"</mark></sub></p> | <p>Define o campo e a direção a usar na pesquisa de registos. </p><p></p><p>Campos ordenáveis:</p><ul><li><code>id</code>, <code>code</code>, <code>salesman\_name</code></li></ul><p>Use '-' antes do nome para ordem decrescente.</p> |
| search         | string                                                                        | <p>Define o termo de pesquisa a utilizar na lista de registos. </p><p></p><p>Campos Pesquisados:</p><ul><li><code>code</code>, <code>salesman\_name</code>,<code>fiscal\_number</code>, etc.</li></ul>                                  |
| code           | integer                                                                       | Código do Vendedor                                                                                                                                                                                                                      |
| salesman\_name | string                                                                        | <p>Nome do Vendedor</p><p></p><p>Sufixos disponíveis:</p><ul><li><code>\_\_search</code>: para pesquisa parcial</li></ul>                                                                                                               |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/salesmen/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "limit": 10,
    "offset": 0,
    "count": 3,
    "next": "https://api.cloudinvoice.net/salesmen/?limit=10&offset=10",
    "previous": null,
    "results":[
        {
            "id": 1,
            "code": 1,
            "salesman_name": "Vendedor Demo",
            "job_title": "",
            "company_phone1": "281380900",
            "company_mobile": "",
            "company_email1": "suporte@cloudinvoice.net"
        },
        ...
    ]
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)

{% hint style="info" %}
**Notas:** Alguns dos campos do termo de pesquisa geral poderão ser incluídos mediante critérios específicos (Ex: Descrição será incluída na pesquisa geral apenas se o termo de pesquisa contiver 3 ou mais caracteres). Por defeito, o comportamento expectável será obter-se todos os items cujo o texto a pesquisar (search) esteja CONTIDO em pelo menos um dos campos incluídos na pesquisa geral.
{% endhint %}


# Create

Cria um novo vendedor.

## Criar Vendedor

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/salesmen/new/`

#### Request Body

| Name                                             | Type    | Description                                                                                                                                                                 |
| ------------------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code                                             | integer | <p>Código do Vendedor</p><p>Valor Único</p>                                                                                                                                 |
| salesman\_name<mark style="color:red;">\*</mark> | string  | Nome do Vendedor                                                                                                                                                            |
| fiscal\_number                                   | string  | Contribuinte                                                                                                                                                                |
| fiscal\_country\_id                              | integer | <p>País Fiscal</p><p></p><p>Consulte a tabela <a href="/documentacao-api/paises/list#lista-de-paises">Países</a>.</p>                                                       |
| job\_title                                       | string  | Cargo                                                                                                                                                                       |
| company\_phone1                                  | string  | Telefone da Empresa                                                                                                                                                         |
| company\_mobile                                  | string  | Telemóvel da Empresa                                                                                                                                                        |
| private\_mobile                                  | string  | Telemóvel Privado                                                                                                                                                           |
| company\_email1                                  | email   | E-mail da Empresa                                                                                                                                                           |
| private\_email1                                  | email   | E-mail Privado                                                                                                                                                              |
| country\_id                                      | integer | <p>País</p><p></p><p>Consulte a tabela <a href="/documentacao-api/paises/list#lista-de-paises">Países</a>.</p>                                                              |
| district\_id                                     | integer | <p>Distrito</p><p></p><p>Consulte a tabela <a href="/documentacao-api/distritos/list">Distritos</a>.</p>                                                                    |
| locality\_id                                     | integer | <p>Concelho</p><p></p><p>Consulte a tabela <a href="/documentacao-api/concelhos/list">Concelhos</a>.</p>                                                                    |
| city                                             | string  | Cidade                                                                                                                                                                      |
| street1                                          | string  | Morada Linha 1                                                                                                                                                              |
| street2                                          | string  | Morada Linha 2                                                                                                                                                              |
| zip\_code                                        | string  | Código Postal                                                                                                                                                               |
| zip\_locale                                      | string  | Localidade                                                                                                                                                                  |
| max\_discount                                    | float   | Desconto Máximo                                                                                                                                                             |
| is\_salesman                                     | boolean | Processa Comissões                                                                                                                                                          |
| fixed\_comission                                 | float   | Comissão Fixa                                                                                                                                                               |
| family\_comission\_level                         | integer | <p>Nível de Comissão por Família<br><br>Consulte a tabela <a href="/documentacao-api/apendice#nivel-de-comissao-por-familia-campo-family_comission_level">Apêndice</a>.</p> |
| comission\_penalty\_id                           | integer | Penalizações de Comissões                                                                                                                                                   |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/salesmen/new/
    -d '{
        "salesman_name": "Vendedor Demo"
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "code": 1,
    "salesman_name": "Vendedor Demo",
    "fiscal_number": "999999990",
    "job_title": "",
    "company_phone1": "",
    "company_mobile": "",
    "private_mobile": "",
    "company_email1": "",
    "private_email1": "",
    "street1": "",
    "street2": "",
    "zip_code": "",
    "zip_locale": "",
    "city": "",
    "max_discount": 100.0,
    "is_salesman": true,
    "fixed_comission": 0.0,
    "party_class_id": 1603,
    "party_class": {
        "code": "V",
        "description": "Vendedores"
    },
    "fiscal_country_id": 1,
    "fiscal_country": {
        "code": "PT",
        "country_name": "Portugal"
    },
    "country_id": 1,
    "country": {
        "code": "PT",
        "country_name": "Portugal"
    },
    "district_id": null,
    "district": null,
    "locality_id": null,
    "locality": null,
    "family_comission_level_id": null,
    "comission_penalty_id": null,
    "comission_penalty": null,
    "family_comission_level": null
}
```

{% endtab %}
{% endtabs %}


# Get

Obtém detalhes do vendedor.

## Obter Vendedor

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/salesmen/:id/`

#### Path Parameters

| Name                                 | Type    | Description      |
| ------------------------------------ | ------- | ---------------- |
| id<mark style="color:red;">\*</mark> | integer | O ID do Vendedor |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/salesmen/1/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "code": 1,
    "salesman_name": "Vendedor Demo",
    "fiscal_number": "999999990",
    "job_title": "",
    "company_phone1": "",
    "company_mobile": "",
    "private_mobile": "",
    "company_email1": "",
    "private_email1": "",
    "street1": "",
    "street2": "",
    "zip_code": "",
    "zip_locale": "",
    "city": "",
    "max_discount": 100.0,
    "is_salesman": true,
    "fixed_comission": 0.0,
    "party_class_id": 1603,
    "party_class": {
        "code": "V",
        "description": "Vendedores"
    },
    "fiscal_country_id": 1,
    "fiscal_country": {
        "code": "PT",
        "country_name": "Portugal"
    },
    "country_id": 1,
    "country": {
        "code": "PT",
        "country_name": "Portugal"
    },
    "district_id": null,
    "district": null,
    "locality_id": null,
    "locality": null,
    "family_comission_level_id": null,
    "comission_penalty_id": null,
    "comission_penalty": null,
    "family_comission_level": null
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Seek

Procura por vendedor a partir do seu código ou número de contribuinte.

## Procurar Vendedor

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/suppliers/seek/:search/`

#### Path Parameters

| Name                                     | Type   | Description                                |
| ---------------------------------------- | ------ | ------------------------------------------ |
| search<mark style="color:red;">\*</mark> | string | Código/Contribuinte do Vendedor a procurar |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/salesmen/seek/123456789/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "code": 1,
    "salesman_name": "Vendedor Demo",
    "fiscal_number": "123456789",
    "job_title": "",
    "company_phone1": "",
    "company_mobile": "",
    "private_mobile": "",
    "company_email1": "",
    "private_email1": "",
    "street1": "",
    "street2": "",
    "zip_code": "",
    "zip_locale": "",
    "city": "",
    "max_discount": 100.0,
    "is_salesman": true,
    "fixed_comission": 0.0,
    "party_class_id": 1603,
    "party_class": {
        "code": "V",
        "description": "Vendedores"
    },
    "fiscal_country_id": 1,
    "fiscal_country": {
        "code": "PT",
        "country_name": "Portugal"
    },
    "country_id": 1,
    "country": {
        "code": "PT",
        "country_name": "Portugal"
    },
    "district_id": null,
    "district": null,
    "locality_id": null,
    "locality": null,
    "family_comission_level_id": null,
    "comission_penalty_id": null,
    "comission_penalty": null,
    "family_comission_level": null
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Exists

Indica, caso exista, o ID do vendedor a partir do seu código ou número de contribuinte.

## Verificar Existência de Vendedor

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/salesmen/exists/:search/`

#### Path Parameters

| Name                                     | Type   | Description                                |
| ---------------------------------------- | ------ | ------------------------------------------ |
| search<mark style="color:red;">\*</mark> | string | Código/Contribuinte do Vendedor a procurar |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/salesmen/exists/1/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "exists": true,
    "id": 1,
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Update

Altera dados de um vendedor.

## Alterar Vendedor

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/salesmen/:id/update/`

#### Request Body

| Name                                             | Type    | Description                                                                                                                                                                 |
| ------------------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code                                             | integer | <p>Código do Vendedor</p><p>Valor Único</p>                                                                                                                                 |
| salesman\_name<mark style="color:red;">\*</mark> | string  | Nome do Vendedor                                                                                                                                                            |
| fiscal\_number                                   | string  | Contribuinte                                                                                                                                                                |
| fiscal\_country\_id                              | integer | <p>País Fiscal</p><p></p><p>Consulte a tabela <a href="/documentacao-api/paises/list#lista-de-paises">Países</a>.</p>                                                       |
| job\_title                                       | string  | Cargo                                                                                                                                                                       |
| company\_phone1                                  | string  | Telefone da Empresa                                                                                                                                                         |
| company\_mobile                                  | string  | Telemóvel da Empresa                                                                                                                                                        |
| private\_mobile                                  | string  | Telemóvel Privado                                                                                                                                                           |
| company\_email1                                  | email   | E-mail da Empresa                                                                                                                                                           |
| private\_email1                                  | email   | E-mail Privado                                                                                                                                                              |
| country\_id                                      | integer | <p>País</p><p></p><p>Consulte a tabela <a href="/documentacao-api/paises/list#lista-de-paises">Países</a>.</p>                                                              |
| district\_id                                     | integer | <p>Distrito</p><p></p><p>Consulte a tabela <a href="/documentacao-api/distritos/list">Distritos</a>.</p>                                                                    |
| locality\_id                                     | integer | <p>Concelho</p><p></p><p>Consulte a tabela <a href="/documentacao-api/concelhos/list">Concelhos</a>.</p>                                                                    |
| city                                             | string  | Cidade                                                                                                                                                                      |
| street1                                          | string  | Morada Linha 1                                                                                                                                                              |
| street2                                          | string  | Morada Linha 2                                                                                                                                                              |
| zip\_code                                        | string  | Código Postal                                                                                                                                                               |
| zip\_locale                                      | string  | Localidade                                                                                                                                                                  |
| max\_discount                                    | float   | Desconto Máximo                                                                                                                                                             |
| is\_salesman                                     | boolean | Processa Comissões                                                                                                                                                          |
| fixed\_comission                                 | float   | Comissão Fixa                                                                                                                                                               |
| family\_comission\_level                         | integer | <p>Nível de Comissão por Família<br><br>Consulte a tabela <a href="/documentacao-api/apendice#nivel-de-comissao-por-familia-campo-family_comission_level">Apêndice</a>.</p> |
| comission\_penalty\_id                           | integer | Penalizações de Comissões                                                                                                                                                   |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/salesmen/1/update/
    -d '{
        "supplier_name": "Vendedor Demo - Update"
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "code": 1,
    "salesman_name": "Vendedor Demo - Update",
    "fiscal_number": "999999990",
    "job_title": "",
    "company_phone1": "",
    "company_mobile": "",
    "private_mobile": "",
    "company_email1": "",
    "private_email1": "",
    "street1": "",
    "street2": "",
    "zip_code": "",
    "zip_locale": "",
    "city": "",
    "max_discount": 100.0,
    "is_salesman": true,
    "fixed_comission": 0.0,
    "party_class_id": 1603,
    "party_class": {
        "code": "V",
        "description": "Vendedores"
    },
    "fiscal_country_id": 1,
    "fiscal_country": {
        "code": "PT",
        "country_name": "Portugal"
    },
    "country_id": 1,
    "country": {
        "code": "PT",
        "country_name": "Portugal"
    },
    "district_id": null,
    "district": null,
    "locality_id": null,
    "locality": null,
    "family_comission_level_id": null,
    "comission_penalty_id": null,
    "comission_penalty": null,
    "family_comission_level": null
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Delete

Apaga um vendedor.

## Apagar Vendedor

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/salesmen/:id/delete/`

#### Path Parameters

| Name                                 | Type    | Description    |
| ------------------------------------ | ------- | -------------- |
| id<mark style="color:red;">\*</mark> | integer | ID do Vendedor |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/salesmen/1/delete/
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Produtos

Tabela para visualização e manipulação das fichas de produtos. Serviços e outros tipos de produtos são também tratados aqui, sendo que as diferenças entre estes e produtos ditos "normais" não justific


# List

Fornece uma lista de todos os produtos existentes.

## Listar Produtos

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/products/`

#### Query Parameters

<table data-search="false"><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>limit</td><td>integer</td><td>Define o número de registos por pesquisa.</td></tr><tr><td>offset</td><td>integer</td><td><p>Indica a posição inicial da pesquisa.</p><p>Retorna a lista de registos compreendida entre <code>offset</code> e <code>offset+limit</code>.</p></td></tr><tr><td>ordering</td><td>string<br><sub><mark style="color:$info;">Default: "id"</mark></sub></td><td><p>Define o campo e a direção a usar na pesquisa de registos. </p><p></p><p>Campos ordenáveis:</p><ul><li><code>id</code>, <code>code</code>, <code>description</code>, <code>short_description</code>, <code>family</code></li></ul><p>Use '-' antes do nome para ordem decrescente.</p></td></tr><tr><td>search</td><td>string</td><td><p>Define o termo de pesquisa a utilizar na lista de registos. </p><p></p><p>Campos Pesquisados:</p><ul><li><code>code</code>, <code>description</code>, <code>short_description</code>, <code>long_description</code>, <code>bar_code</code>, etc.</li></ul></td></tr><tr><td>code</td><td>integer</td><td><p>Código do Produto</p><p></p><p>Sufixos disponíveis:</p><ul><li><code>__search</code>: para pesquisa parcial</li></ul></td></tr><tr><td>description</td><td>string</td><td><p>Descrição</p><p></p><p>Sufixos disponíveis:</p><ul><li><code>__search</code>: para pesquisa parcial</li></ul></td></tr><tr><td>short_description</td><td>string</td><td><p>Descrição Curta</p><p></p><p>Sufixos disponíveis:</p><ul><li><code>__search</code>: para pesquisa parcial</li></ul></td></tr><tr><td>long_description</td><td>string</td><td><p>Descrição Alargada</p><p></p><p>Sufixos disponíveis:</p><ul><li><code>__search</code>: para pesquisa parcial</li></ul></td></tr><tr><td>family</td><td>integer</td><td>Família</td></tr><tr><td>sub_family</td><td>integer</td><td>Sub-Família</td></tr><tr><td>bar_code</td><td>string</td><td><p>Código de Barras</p><p></p><p>Sufixos disponíveis:</p><ul><li><code>__search</code>: para pesquisa parcial</li></ul></td></tr></tbody></table>

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/products/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "limit": 10,
    "offset": 0,
    "count": 46,
    "next": "https://api.cloudinvoice.net/products/?limit=10&offset=10",
    "previous": null,
    "results": [
        {
            "id": 1,
            "code": "PROD1",
            "bar_code": "5449000000996",
            "description": "Produto Standard 1",
            "short_description": "Produto Standard 1",
            "vat_tax_rate": 23.0,
            "unit_price": 100.0,
            "unit_price_tax_inc": 123.0,
            "family_id": 1,
            "family": {
                "code": "FAM1",
                "description": "Família 1"
            },
            "sub_family_id": null,
            "sub_family": null,
            "product_type_id": 131,
            "product_type": {
                "code": "01",
                "description": "Produto"
            },
            "product_category_id": 211,
            "product_category": {
                "code": "M",
                "description": "Mercadorias"
            },
            "measure_unit_id": 1,
            "measure_unit": {
                "code": "UNI",
                "description": "Unidade"
            },
            "vat_tax_id": 1,
            "vat_tax": {
                "code": 1,
                "description": "Taxa Normal"
            }
        },
        ...
    ]
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)

{% hint style="info" %}
**Notas:** Alguns dos campos do termo de pesquisa geral poderão ser incluídos mediante critérios específicos (Ex: Descrição será incluída na pesquisa geral apenas se o termo de pesquisa contiver 3 ou mais caracteres). Por defeito, o comportamento expectável será obter-se todos os items cujo o texto a pesquisar (search) esteja CONTIDO em pelo menos um dos campos incluídos na pesquisa geral.
{% endhint %}


# Create

Cria um novo produto.

## Criar Produto

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/products/new/`

#### Request Body

| Name                                          | Type                                                                      | Description                                                                                                                                                                                            |
| --------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| code                                          | <p>string<br><sub><mark style="color:$info;">Valor Único</mark></sub></p> | <p>Código do Produto<br><br>Gerado automaticamente quando não fornecido.</p>                                                                                                                           |
| family\_id<mark style="color:red;">\*</mark>  | integer                                                                   | <p>Família<br><br>Consulte a tabela <a href="/documentacao-api/familias/list">Famílias</a> para saber mais.</p>                                                                                        |
| sub\_family\_id                               | integer                                                                   | <p>Sub-Família<br><br>Consulte a tabela <a href="/documentacao-api/sub-familias/list">Sub-Famíílias</a>  para saber mais.</p>                                                                          |
| product\_type\_id                             | integer                                                                   | <p>Tipo de Produto<br><br>Consulte a tabela <a href="/documentacao-api/apendice#tipos-de-produtos-campo-product_type">Apêndice</a> para saber mais.</p>                                                |
| product\_category\_id                         | integer                                                                   | <p>Categoria de Produto<br><br>Consulte a tabela <a href="/documentacao-api/apendice#categorias-de-produtos-campo-product_category">Apêndice</a> para saber mais.</p>                                  |
| description<mark style="color:red;">\*</mark> | string                                                                    | Descrição do Produto                                                                                                                                                                                   |
| short\_description                            | string                                                                    | Descrição Curta                                                                                                                                                                                        |
| long\_description                             | string                                                                    | <p>Descrição Longa.</p><p><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo está dependente da configuração <code>use\_long\_description</code></p> |
| measure\_unit\_id                             | integer                                                                   | <p>Unidade de Medida<br><br>Consulte a tabela <a href="/documentacao-api/unidades-de-medida/list">Unidades de Medida</a> para saber mais.</p>                                                          |
| vat\_tax\_id                                  | integer                                                                   | <p>Taxa de IVA<br><br>Consulte a tabela <a href="/documentacao-api/taxas/list">Taxas</a> para saber mais.</p>                                                                                          |
| bar\_code                                     | string                                                                    | <p>Código de Barras<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Editável apenas se <code>bar\_code\_type\_id</code> estiver preenchido</p>                          |
| bar\_code\_type\_id                           | integer                                                                   | <p>Tipo do Código de Barras<br><br>Consulte a tabela <a href="/documentacao-api/apendice#tipos-de-codigos-de-barras-campo-bar_code_type">Apêndice</a> para saber mais.</p>                             |
| do\_stock\_management                         | boolean                                                                   | Movimenta Stock                                                                                                                                                                                        |
| can\_have\_negative\_stock                    | boolean                                                                   | Pode ter stock negativo                                                                                                                                                                                |
| use\_serial\_number                           | boolean                                                                   | <p>Usar Nº de Série</p><p><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo está dependente da configuração <code>use\_serial\_numbers</code></p>   |
| use\_internal\_serial\_number                 | boolean                                                                   | <p>Usar Nº de Série Interno<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Editável apenas se <code>use\_serial\_number</code> estiver activo</p>                      |
| has\_lots                                     | boolean                                                                   | <p>Usar Lotes<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo está dependente da configuração <code>use\_lots</code></p>                       |
| use\_sizes\_colors                            | boolean                                                                   | <p>Usar Cores e Tamanhos<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo está dependente da configuração <code>use\_sizes\_colors</code></p>   |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/products/new/
    -d '{
        "code": "PROD1",
        "description": "Produto 1"
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "code": "PROD1",
    "description": "Produto Standard 1",
    "short_description": "Produto Standard 1",
    "family_id": 1,
    "family": {
        "code": "FAM1",
        "description": "Família 1"
    },
    "sub_family_id": null,
    "sub_family": null,
    "product_type_id": 131,
    "product_type": {
        "code": "01",
        "description": "Produto"
    },
    "product_category_id": 211,
    "product_category": {
        "code": "M",
        "description": "Mercadorias"
    },
    "product_type_saft_id": 3271,
    "product_type_saft": {
        "code": "P",
        "description": "Produtos"
    },
    "vat_tax_id": 1,
    "vat_tax": {
        "code": 1,
        "description": "Taxa Normal"
    },
    "vat_tax_rate": 23.0,
    "bar_code": "2000000000015",
    "bar_code_type_id": 153,
    "bar_code_type": {
        "code": "I",
        "description": "Interno EAN13"
    },
    "do_stock_management": true,
    "can_have_negative_stock": true,
    "physical_qty": 10.0,
    "measure_unit_id": 1,
    "measure_unit": {
        "code": "UNI",
        "description": "Unidade"
    },
    "use_serial_number": false,
    "use_internal_serial_number": false,
    "has_lots": false,
    "use_sizes_colors": false,
    "last_cost_price": 0.0,
    "average_cost_price": 0.0,
    "profit_margin": 0.0,
    "unit_price": 100.0,
    "unit_price_tax_inc": 123.0
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Get

Obtém detalhes de um produto.

## Obter Produto

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/products/:id/`

#### Path Parameters

| Name | Type    | Description   |
| ---- | ------- | ------------- |
| id   | integer | ID do Produto |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/products/1/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "code": "PROD1",
    "description": "Produto Standard 1",
    "short_description": "Produto Standard 1",
    "family_id": 1,
    "family": {
        "code": "FAM1",
        "description": "Família 1"
    },
    "sub_family_id": null,
    "sub_family": null,
    "product_type_id": 131,
    "product_type": {
        "code": "01",
        "description": "Produto"
    },
    "product_category_id": 211,
    "product_category": {
        "code": "M",
        "description": "Mercadorias"
    },
    "product_type_saft_id": 3271,
    "product_type_saft": {
        "code": "P",
        "description": "Produtos"
    },
    "vat_tax_id": 1,
    "vat_tax": {
        "code": 1,
        "description": "Taxa Normal"
    },
    "vat_tax_rate": 23.0,
    "bar_code": "2000000000015",
    "bar_code_type_id": 153,
    "bar_code_type": {
        "code": "I",
        "description": "Interno EAN13"
    },
    "do_stock_management": true,
    "can_have_negative_stock": true,
    "physical_qty": 10.0,
    "measure_unit_id": 1,
    "measure_unit": {
        "code": "UNI",
        "description": "Unidade"
    },
    "use_serial_number": false,
    "use_internal_serial_number": false,
    "has_lots": false,
    "use_sizes_colors": false,
    "last_cost_price": 0.0,
    "average_cost_price": 0.0,
    "profit_margin": 0.0,
    "unit_price": 100.0,
    "unit_price_tax_inc": 123.0
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Seek

Procura por produto a partir do seu código ou código de barras.

## Procurar Produto

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/products/seek/:search/`

#### Path Parameters

| Name   | Type   | Description                                    |
| ------ | ------ | ---------------------------------------------- |
| search | string | Código/Código de barras do Produto a pesquisar |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/products/seek/999999990/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "code": "PROD1",
    "description": "Produto Standard 1",
    "short_description": "Produto Standard 1",
    "family_id": 1,
    "family": {
        "code": "FAM1",
        "description": "Família 1"
    },
    "sub_family_id": null,
    "sub_family": null,
    "product_type_id": 131,
    "product_type": {
        "code": "01",
        "description": "Produto"
    },
    "product_category_id": 211,
    "product_category": {
        "code": "M",
        "description": "Mercadorias"
    },
    "product_type_saft_id": 3271,
    "product_type_saft": {
        "code": "P",
        "description": "Produtos"
    },
    "vat_tax_id": 1,
    "vat_tax": {
        "code": 1,
        "description": "Taxa Normal"
    },
    "vat_tax_rate": 23.0,
    "bar_code": "2000000000015",
    "bar_code_type_id": 153,
    "bar_code_type": {
        "code": "I",
        "description": "Interno EAN13"
    },
    "do_stock_management": true,
    "can_have_negative_stock": true,
    "physical_qty": 10.0,
    "measure_unit_id": 1,
    "measure_unit": {
        "code": "UNI",
        "description": "Unidade"
    },
    "use_serial_number": false,
    "use_internal_serial_number": false,
    "has_lots": false,
    "use_sizes_colors": false,
    "last_cost_price": 0.0,
    "average_cost_price": 0.0,
    "profit_margin": 0.0,
    "unit_price": 100.0,
    "unit_price_tax_inc": 123.0
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Exists

Indica, caso exista, o ID do produto a partir do seu código ou código de barras.

## Verificar Existência de Produto

<mark style="color:blue;">`GET`</mark> `https://api.cloudinvoice.net/products/exists/:search/`

#### Path Parameters

| Name   | Type   | Description                                    |
| ------ | ------ | ---------------------------------------------- |
| search | string | Código/Código de barras do Produto a pesquisar |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl https://api.cloudinvoice.net/products/exists/1/
    -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "exists": true,
    "id": 1,
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)


# Update

Altera dados de um produto.

## Alterar Produto

<mark style="color:green;">`POST`</mark> `https://api.cloudinvoice.net/products/:id/update/`

#### Path Parameters

| Name | Type    | Description   |
| ---- | ------- | ------------- |
| id   | integer | ID do Produto |

#### Request Body

| Name                          | Type                                                                      | Description                                                                                                                                                                                                                                                                                                    |
| ----------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code                          | <p>string<br><sub><mark style="color:$info;">Valor Único</mark></sub></p> | <p>Código do Cliente<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A alteração deste campo apenas é permitida enquanto este não for usado.</p>                                                                                                                                |
| description                   | string                                                                    | Descrição do Produto                                                                                                                                                                                                                                                                                           |
| short\_description            | string                                                                    | Descrição Curta                                                                                                                                                                                                                                                                                                |
| family\_id                    | integer                                                                   | <p>Família<br><br>Consulte a tabela <a href="/documentacao-api/familias/list">Famílias</a> para saber mais.</p>                                                                                                                                                                                                |
| long\_description             | string                                                                    | <p>Descrição Longa.</p><p><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo está dependente da configuração <code>use\_long\_description</code></p>                                                                                                         |
| sub\_family\_id               | integer                                                                   | <p>Sub-Família<br><br>Consulte a tabela <a href="/documentacao-api/sub-familias/list#lista-de-sub-familias">Sub-Famílias</a> para saber mais.</p>                                                                                                                                                              |
| product\_type\_id             | integer                                                                   | <p>Tipo de Produto<br><br>Consulte a tabela <a href="/documentacao-api/apendice#tipos-de-produtos-campo-product_type">Apêndice</a> para saber mais.<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A alteração deste campo apenas é permitida enquanto este não for usado.</p> |
| product\_category\_id         | integer                                                                   | <p>Categoria de Produto<br><br>Consulte a tabela <a href="/documentacao-api/apendice#categorias-de-produtos-campo-product_category">Apêndice</a> para saber mais.</p>                                                                                                                                          |
| measure\_unit\_id             | integer                                                                   | <p>Unidade de Medida<br><br>Consulte a tabela <a href="/documentacao-api/unidades-de-medida/list">Unidades de Medida</a> para saber mais.</p>                                                                                                                                                                  |
| vat\_tax\_id                  | integer                                                                   | <p>Taxa de IVA<br><br>Consulte a tabela <a href="/documentacao-api/taxas/list">Taxas</a> para saber mais.</p>                                                                                                                                                                                                  |
| bar\_code                     | string                                                                    | <p>Código de Barras<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Editável apenas se <code>bar\_code\_type\_id</code> estiver preenchido</p>                                                                                                                                  |
| bar\_code\_type\_id           | integer                                                                   | <p>Tipo do Código de Barras<br><br>Consulte a tabela <a href="/documentacao-api/apendice#tipos-de-codigos-de-barras-campo-bar_code_type">Apêndice</a> para saber mais.</p>                                                                                                                                     |
| do\_stock\_management         | boolean                                                                   | Movimenta Stock                                                                                                                                                                                                                                                                                                |
| can\_have\_negative\_stock    | boolean                                                                   | Pode ter stock negativo                                                                                                                                                                                                                                                                                        |
| use\_serial\_number           | boolean                                                                   | <p>Usar Nº de Série.</p><p><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo está dependente da configuração <code>use\_serial\_numbers</code></p>                                                                                                          |
| use\_internal\_serial\_number | boolean                                                                   | <p>Usar Nº de Série Interno<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> Editável apenas se <code>use\_serial\_number</code> estiver activo</p>                                                                                                                              |
| has\_lots                     | boolean                                                                   | <p>Usar Lotes<br><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo está dependente da configuração <code>use\_lots</code></p>                                                                                                                               |
| use\_sizes\_colors            | boolean                                                                   | <p>Usar Cores e Tamanhos</p><p><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> A utilização deste campo está dependente da configuração <code>use\_sizes\_colors</code></p>                                                                                                        |

{% tabs %}
{% tab title="Exemplo de Pedido" %}

```shell
curl -X POST https://api.cloudinvoice.net/products/:id/update/
    -d '{
        "description": "Produto 1 - Update"
    }'
```

{% endtab %}

{% tab title="Exemplo de Resposta" %}

```json
{
    "id": 1,
    "code": "PROD1",
    "description": "Produto Standard 1 - Update",
    "short_description": "Produto Standard 1",
    "family_id": 1,
    "family": {
        "code": "FAM1",
        "description": "Família 1"
    },
    "sub_family_id": null,
    "sub_family": null,
    "product_type_id": 131,
    "product_type": {
        "code": "01",
        "description": "Produto"
    },
    "product_category_id": 211,
    "product_category": {
        "code": "M",
        "description": "Mercadorias"
    },
    "product_type_saft_id": 3271,
    "product_type_saft": {
        "code": "P",
        "description": "Produtos"
    },
    "vat_tax_id": 1,
    "vat_tax": {
        "code": 1,
        "description": "Taxa Normal"
    },
    "vat_tax_rate": 23.0,
    "bar_code": "2000000000015",
    "bar_code_type_id": 153,
    "bar_code_type": {
        "code": "I",
        "description": "Interno EAN13"
    },
    "do_stock_management": true,
    "can_have_negative_stock": true,
    "physical_qty": 10.0,
    "measure_unit_id": 1,
    "measure_unit": {
        "code": "UNI",
        "description": "Unidade"
    },
    "use_serial_number": false,
    "use_internal_serial_number": false,
    "has_lots": false,
    "use_sizes_colors": false,
    "last_cost_price": 0.0,
    "average_cost_price": 0.0,
    "profit_margin": 0.0,
    "unit_price": 100.0,
    "unit_price_tax_inc": 123.0
}
```

{% endtab %}
{% endtabs %}

Para ver exemplos de pedidos nas várias linguagens, consulte a página[ Exemplos de Pedidos.](/introducao/exemplos-de-pedidos)




---

[Next Page](/llms-full.txt/1)