Início #

A API CloudInvoice dá-lhe a oportunidade de interagir com a sua conta CloudInvoice a partir de aplicações externas.

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.

Tenha em atenção que os URLs da API acabam sempre com '/'.

$ curl https://www.cloudinvoice.net/v3/info
$ curl https://www.cloudinvoice.net/v3/info/

Pedidos #

Os pedidos são feitos ao endereço https://www.cloudinvoice.net/v3/, acrescentando-lhe o end-point da acção pretendida.
Nesta documentação, usaremos pedidos realizados a partir do software cURL como exemplo.

$ curl https://www.cloudinvoice.net/v3/
    -H "Content-Type: application/json"
{
    "status": "OK"
}

Autenticação #

A API usa autenticação por Token. 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.
Deverá ser incluído em cada pedido o Header HTTP: Authorization: Token <token>

Pedido com Autenticação
$ curl https://www.cloudinvoice.net/v3/info/
    -H "Content-Type: application/json"
    -H "Authorization: Token 329c2d5cadd96ccce7b0b0f2653e8d08f61ddd52"

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

  1. 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.
  2. Usando a própria API: Pode obter um Token fazendo um pedido ao end-point /login, incluindo as suas credenciais de autenticação, obtendo na resposta o Token que poderá utilizar nos pedidos posteriores.

Erros #

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

Exemplo de Resposta com Erro
{
    "status_code": 400,
    "error_type": "api_error",
    "generic_msg": "A server error occurred.",
    "detail_msg": "",
    "error_code": "validation_error",
    "errors": {
        "non_field_errors": "Não existe nenhum cliente com este código."
    }
}

Notas #

Para que os exemplos não se tornem demasiado extensos, omitimos, muitas vezes, alguns campos das respostas que consideramos menos relevantes no contexto do exemplo. Sempre que encontrar nos exemplos o sinal '...' (reticências), é o indicador de que existem campos na resposta que foram omitidos no exemplo.

API - Geral #

Apresentamos de seguida alguns end-points de propósito geral existentes na API CloudInvoice.
Tratam-se maioritariamente de end-points relacionados com autenticação e/ou recolha de informações gerais sobre a Empresa ou o Token

Login /login POST

Gera um Token de Acesso ou fornece um Token válido para as credenciais fornecidas.

Parâmetros  
username

Utilizador string

Preenchimento Obrigatório

password

Password string

Preenchimento Obrigatório

$ curl -X POST https://www.cloudinvoice.net/v3/login/
    -d '{
        "username": "user@sample.com",
        "password": "pFS2VwMk"
    }'
{
    "token": "329c2d5cadd96ccce7b0b0f2653e8d08f61ddd52"
}

Informações do Token /info GET

Fornece informações sobre Sessão do Token usado, tais como o utilizador, localização, terminal e caixa que usa, assim como todas as permissões associadas.

$ curl https://www.cloudinvoice.net/v3/info/
{
    "token": "329c2d5cadd96ccce7b0b0f2653e8d08f61ddd52",
    "id": 1,
    "username": "user@sample.com",
    "first_name": "Sample",
    "full_name": "Sample User",
    "is_active": true,
    "is_staff": false,
    "role": "user",
    "created": "2020-06-18T12:08:10.866599+00:00",
    "company_id": 2,
    "company_code": "demo",
    "company_name": "Empresa & Demo",
    "location_id": 1,
    "location": "Localização 1",
    "terminal_id": 1,
    "terminal": "Terminal 1",
    "till_id": 1,
    "till": "Caixa 1",
    "app_session_id": 5,
    "app_session": "Sessão de  Caixa 1, Data: 2020-06-18",
    "permissions": {
        ...
    }
}

API - Tabelas #

Clientes #

Parâmetros

code

Código int

Valor Único, Preenchimento Obrigatório

customer_name

Nome do Cliente string

Preenchimento Obrigatório, Tamanho: 200

commercial_name

Designação Comercial string

Tamanho: 200

fiscal_country

País Fiscal int

Relação com o campo 'id' da tabela 'Países'.

Preenchimento Obrigatório

fiscal_number

Contribuinte string

Este valor será validado consoante os formatos aceites no País Fiscal (fiscal_country).
De momento, são aplicadas validações apenas aos países: PT.
Para Portugal (PT), se não for fornecido valor, o campo será automaticamente preenchido com o valor '999999990'.

fiscal_status_type

Tipo de Contribuinte int

Pode tomar os valores:

  • 1591 - Desconhecido
  • 1592 - Consumidor final
  • 1593 - Sujeito Passivo de IVA

Default: Consumidor Final

is_vat_exempt

Entidade Isenta de IVA bool

Default: false

vat_exempt_tax_exemption

Taxa de IVA Isenta a Usar int

Relação com o campo 'id' da tabela 'Tabelas de Impostos'.

O preenchimento deste campo é obrigatório quando is_vat_exempt = true.

is_cash_vat_scheme

Regime IVA de Caixa bool

Default: false

street1

Morada Linha 1 string

O preenchimento deste campo é obrigatório quando fiscal_status_type = 1593.

Tamanho: 255

street2

Morada Linha 2 string

Tamanho: 255

city

Cidade string

Tamanho: 100

zip_code

Código Postal string

Este valor será validado consoante os formatos aceites no País (country).
De momento, são aplicadas validações apenas aos países: PT.

O preenchimento deste campo é obrigatório quando fiscal_status_type = 1593.

zip_locale

Localidade string

O preenchimento deste campo é obrigatório quando fiscal_status_type = 1593.

country

País int

Relação com o campo 'id' da tabela 'Países'

contact1

Nome de Contacto #1 string

Tamanho: 100

phone1

Telefone #1 string

Tamanho: 100

mobile1

Telemóvel #1 string

Tamanho: 100

fax1

Fax #1 string

Tamanho: 100

email1

E-mail #1 string

Tamanho: 100

contact2

Nome de Contacto #2 string

Tamanho: 100

phone2

Telefone #2 string

Tamanho: 100

mobile2

Telemóvel #2 string

Tamanho: 100

fax2

Fax #2 string

Tamanho: 100

email2

E-mail #2 string

Tamanho: 100

web_address

Endereço Web string

Tamanho: 100

price_line

Linha de Preços int

Relação com o campo 'id' da tabela 'Linhas de Preços'

payment_method

Método de Pagamento string

Relação com o campo 'id' da tabela 'Formas de Pagamento'

global_discount1

Desconto Global decimal

Valores: entre 0 e 100

line_discount1

Desconto #1 decimal

Valores: entre 0 e 100

line_discount2

Desconto #2 decimal

Valores: entre 0 e 100

has_withholding

Retenção na Fonte bool

A utilização deste campo, tal como os campos relacionados com retenção na fonte, pode estar limitada por opções de configuração do CloudInvoice.

Default: false

withholding_type

Tipo de Retenção int

Pode tomar os valores:

  • 1631 - Imposto sobre Rendimento de pessoas Singulares
  • 1632 - Imposto sobre Rendimento de pessoas Colectivas
  • 1633 - Imposto do Selo
withholding_tax

Taxa de Retenção decimal

Valores: entre 0 e 100

withholding_description

Motivo de Retenção string

Tamanho: 60

obs

Observações string

Tamanho: 255

Listar Clientes /customers GET

Fornece uma lista de todos os clientes existentes.

$ curl https://www.cloudinvoice.net/v3/customers/
{
    "results": [
        {
            "id": 1,
            "code": 1,
            "customer_name": "Consumidor Final",
            "fiscal_number": "999999990",
            "current_balance": 0,
            "phone1": 0,
            "street1": 0
        },
        {
            "id": 2,
            "code": 2,
            "customer_name": "Client Demo",
            "fiscal_number": "503217239",
            "current_balance": 123.0,
            "street1": "Av. Dr. Mateus Teixeira de Azevedo, Lote 3 R/C Esq.",
            "phone1": 0
        }
    ],
    "count_total": 2
}

Procurar Cliente /customer-seek/<search> GET

Procurar cliente por nome ou número de identificação fiscal (NIF).
O termo de procura search pode conter tanto o NIF fiscal_number como o nome do cliente customer_name e deverá ser, em ambos os casos, precedido do código ISO (alpha2) do país fiscal_country separado por hiffen (ex: "PT-503217239" ou "PT-Client Demo").
A reposta trará um único resultado, mas apenas se for encontrada uma, e apenas uma, combinação perfeita do termo de procura.

$ curl https://www.cloudinvoice.net/v3/customer-seek/PT-503217239/
{
    "id": 1,
    "code": 1,
    "customer_name": "Client Demo",
    "commercial_name": "",
    "party_class": 1601,
    "fiscal_number": "503217239",
    "fiscal_status_type": 1593,
    "fiscal_country_id": 1,
    "fiscal_country": "Portugal",
    "is_vat_exempt": false,
    "is_cash_vat_scheme": false,
    "street1": "Av. Dr. Mateus Teixeira de Azevedo, Lote 3 R/C Esq.",
    "street2": "",
    "zip_code": "8800-379",
    "zip_locale": "Tavira",
    "locality_id": null,
    "locality": "",
    "district_id": null,
    "district": "",
    "country_id": 1,
    "country": "Portugal",
    "phone1": "",
    "mobile1": "",
    "fax1": "",
    "email1": "",
    "web_address": "",
    "zone_id": 1,
    "zone": "Nacional",
    "obs": "",
    ...
}

Criar Cliente /customer/new POST

Cria um novo cliente.

$ curl -X POST https://www.cloudinvoice.net/v3/customer/new/
    -d '{
        "code": 21,
        "customer_name": "Cliente",
        "fiscal_number": "999999990",
        "fiscal_country": 1,
        "fiscal_status_type": 1592,
        "email1": "suporte@cloudinvoice.net",
        "phone1": "281380900",
        "street1": "Avenida Doutor Mateus Teixeira de Azevedo Lote 3 R/C",
        "zip_code": "8800-379",
        "zip_locale": "Tavira",
        "country":1
    }'
{
    "id": 6,
    "code": 21,
    "customer_name": "Cliente",
    "commercial_name": "",
    "party_class": 1601,
    "fiscal_number": "999999990",
    "fiscal_status_type": 1592,
    "fiscal_country_id": 1,
    "fiscal_country": "Portugal",
    "is_vat_exempt": false,
    "is_cash_vat_scheme": false,
    "street1": "Avenida Doutor Mateus Teixeira de Azevedo Lote 3 R/C",
    "street2": "",
    "zip_code": "8800-379",
    "zip_locale": "Tavira",
    "locality_id": null,
    "locality": "",
    "district_id": null,
    "district": "",
    "country_id": 1,
    "country": "Portugal",
    "phone1": "281380900",
    "mobile1": "",
    "fax1": "",
    "email1": "suporte@cloudinvoice.net",
    "web_address": "",
    "zone_id": 1,
    "zone": "Nacional",
    "obs": "",
    ...
}

Obter Cliente /customer/<id> GET

Obter informação de um cliente a partir do seu ID.

$ curl https://www.cloudinvoice.net/v3/customer/1/
{
    "id": 1,
    "code": 1,
    "customer_name": "Consumidor Final",
    "commercial_name": "",
    "party_class": 1601,
    "fiscal_number": "999999990",
    "fiscal_status_type": 1592,
    "fiscal_country_id": 1,
    "fiscal_country": "Portugal",
    "is_vat_exempt": false,
    "is_cash_vat_scheme": false,
    "street1": "",
    "street2": "",
    "zip_code": "",
    "zip_locale": "",
    "locality_id": null,
    "locality": "",
    "district_id": null,
    "district": "",
    "country_id": 1,
    "country": "Portugal",
    "phone1": "",
    "mobile1": "",
    "fax1": "",
    "email1": "",
    "web_address": "",
    "zone_id": 1,
    "zone": "Nacional",
    "obs": "",
    ...
}

Alterar Cliente /customer/<pk>/update POST

Alterar cliente.

$ curl -X POST https://www.cloudinvoice.net/v3/customer/6/update/
    -d '{
        "mobile1": "912345678",
        "obs": "Contactar preferencialmente a partir das 19h"
    }'
{
    "id": 6,
    "code": 21,
    "customer_name": "Cliente",
    "commercial_name": "",
    "party_class": 1601,
    "fiscal_number": "999999990",
    "fiscal_status_type": 1592,
    "fiscal_country_id": 1,
    "fiscal_country": "Portugal",
    "is_vat_exempt": false,
    "is_cash_vat_scheme": false,
    "street1": "Avenida Doutor Mateus Teixeira de Azevedo Lote 3 R/C",
    "street2": "",
    "zip_code": "8800-379",
    "zip_locale": "Tavira",
    "locality_id": null,
    "locality": "",
    "district_id": null,
    "district": "",
    "country_id": 1,
    "country": "Portugal",
    "phone1": "281380900",
    "mobile1": "912345678",
    "fax1": "",
    "email1": "suporte@cloudinvoice.net",
    "web_address": "",
    "zone_id": 1,
    "zone": "Nacional",
    "obs": "Contactar preferencialmente a partir das 19h",
    ...
}

Famílias de Produtos #

Parâmetros

code

Código string

Valores deverão ser compostos apenas por letras, números, caracteres sublinhado, hífenes, pontos ou barras.

Preenchimento Obrigatório, Valor Único, Tamanho: 20

description

Descrição string

Preenchimento Obrigatório, Tamanho: 100

Famílias de Produtos /families GET

Fornece uma lista de todas as famílias e sub-famílias de produtos existentes.

$ curl https://www.cloudinvoice.net/v3/families/
{
    "families": [
        {
            "id": 1,
            "code": "FAM1",
            "description": "Família 1",
            "sub_families": [
                {
                    "id": 1,
                    "code": "SUB1.1",
                    "description": "SubFamília 1-1",
                    "family_id": 1
                }
            ]
        },
        {
            "id": 2,
            "code": "FAM2",
            "description": "Família 2",
            "sub_families": []
        },
        ...
    ]
}

Procurar Família /family-seek/<code> GET

Procurar família de produtos por código.

$ curl https://www.cloudinvoice.net/v3/family-seek/FAM2/
{
    "id": 2,
    "code": "FAM2",
    "description": "Família 2"
}

Criar Família de Produtos /family/new POST

Cria uma nova família de produtos.

$ curl -X POST https://www.cloudinvoice.net/v3/family/new/
    -d '{
        "code": "FAM4",
        "description": "Família 4"
    }'
{
    "id": 13,
    "code": "FAM4",
    "description": "Família 4"
}

Produtos #

Parâmetros

code

Código string

Valores deverão ser compostos apenas por letras, números, caracteres sublinhado, hífenes, pontos ou barras.

Valor Único, Preenchimento Obrigatório, Tamanho: 30

description

Descrição string

Preenchimento Obrigatório, Tamanho: 255

short_description

Descrição Curta string

Tamanho: 100

long_description

Descrição Alargada string

A utilização deste campo pode estar limitada por opções de configuração do CloudInvoice.

Tamanho: 10000

family

Família int

Relação com o campo 'id' da tabela 'Famílias de Produtos'.

Preenchimento Obrigatório

product_type

Tipo de Produto int

Pode tomar os valores:

  • 131 - Produto
  • 132 - Serviço
  • 135 - Transformado
  • 140 - Impostos
  • 141 - Outros
  • 144 - Rapel
  • 146 - Impostos Especiais de Consumo

A utilização de alguns dos valores possíveis para este campo pode ser limitada por opções de configuração do CloudInvoice ou pelo tipo de licença que possui.

Preenchimento Obrigatório

product_category

Categoria de Produto int

Pode tomar os valores:

  • 211 - Mercadorias
  • 212 - Matérias-primas, subsidiárias e de consumo
  • 213 - Produtos acabados e intermédios
  • 214 - Subprodutos, desperdícios e refugos
  • 215 - Produtos e trabalhos em curso
  • 217 - Outros (não contabilizável em Inventário)

Default: Mercadorias

bar_code_type

Tipo de Código de Barras int

Pode tomar os valores:

  • 151 - (Nenhum)
  • 152 - Fornecedor
  • 153 - Interno EAN13
  • 154 - Valor Incluído
  • 155 - Peso Incluído
  • 156 - Inclui Quantidade
  • 157 - Inclui Preço Unitário
  • 158 - Número de Série
  • 159 - Inclui Lote
  • 162 - Produtor

A utilização de alguns dos valores possíveis para este campo pode ser limitada pelo tipo de produto, opções de configuração do CloudInvoice ou pelo tipo de licença que possui.

Default: (Nenhum)

bar_code

Código de Barras string

O preenchimento deste campo é obrigatório quando bar_code_type != 151.

Tamanho: 30

vat_tax

Taxa de IVA int

Relação com o campo 'id' da tabela 'Tabelas de Impostos'.

is_exempt_withholding

Isento de Retenção na Fonte bool

A utilização deste campo pode estar limitada por opções de configuração do CloudInvoice.

Default: false

withholding_type

Tipo de Retenção int

Pode tomar os valores:

  • 1631 - Imposto sobre Rendimento de pessoas Singulares
  • 1632 - Imposto sobre Rendimento de pessoas Colectivas
  • 1633 - Imposto do Selo

A utilização deste campo pode estar limitada por opções de configuração do CloudInvoice.

measure_unit

Unidade de Medida int

Relação com o campo 'id' da tabela 'Unidades de Medida'.

do_stock_management

Movimenta Stock bool

Default: variável

can_have_negative_stock

Pode ter stock negativo bool

Aplicável apenas se do_stock_management = true.

Default: false

use_serial_number

Tem Nº de Série bool

Incompatível com has_lots = true.

Default: false

use_internal_serial_number

Usar Nº de Série Interno bool

Aplicável apenas se use_serial_number = true.

Default: false

has_lots

Tem Lotes bool

Incompatível com use_serial_number = true.

Default: false

gross_weight

Peso Bruto decimal

net_weight

Peso Líquido decimal

profit_margin

Margem de Lucro de Referência decimal

max_discount

Desconto Máximo decimal

Valores: entre 0 e 100

obs

Observações string

Tamanho: 255

Listar Produtos /products GET

Fornece uma lista de todos os produtos existentes.

$ curl https://www.cloudinvoice.net/v3/products/
{
    "results": [
        {
            "id": 1,
            "code": "PROD1",
            "description": "Produto Standard 1",
            "short_description": "Produto Standard 1",
            "family_id": 1,
            "family": "Família 1",
            "family_code": "FAM1",
            "family_description": "Família 1",
            "unit_price_raw": 100.0,
            "unit_price": "100.00 €",
            "unit_price_tax_inc_raw": 123.0,
            "unit_price_tax_inc": "123.00 €",
            "average_cost_price_raw": 0,
            "average_cost_price": "0.00 €",
            "last_cost_price_raw": 0,
            "last_cost_price": "0.00 €",
            "do_stock_management": 1,
            "physical_qty": 9.0,
            "use_serial_number": 0,
            "has_lots": 0,
            "read_weight_from_scale": 0
        },
        ...
    ],
    "count_total": 10
}

Procurar Produto /product-seek/<code> GET

Procurar produto por código.

$ curl https://www.cloudinvoice.net/v3/product-seek/PROD1/
{
    "id": 1,
    "code": "PROD1",
    "description": "Produto Standard 1",
    "short_description": "Produto Standard 1",
    "family_id": 1,
    "family": "Família 1 (FAM1)",
    "sub_family_id": null,
    "sub_family": "",
    "product_type": 131,
    "product_type_saft": 3271,
    "product_category": 211,
    "bar_code_type": 153,
    "bar_code": "2000000000015",
    "vat_tax_id": 1,
    "vat_tax": "Taxa Normal",
    "vat_tax_rate": 23.0,
    "vat_exemption_id": null,
    "unit_price": 100.0,
    "unit_price_tax_inc": 123.0,
    "last_cost_price": 0.0,
    "average_cost_price": 0.0,
    "profit_margin": 0.0,
    "do_stock_management": true,
    "can_have_negative_stock": true,
    "physical_qty": 9.0,
    "global_physical_qty": 9.0,
    "location_physical_qty": 9.0,
    "total_entry_qty": 0.0,
    "total_exit_qty": 1.0,
    "measure_unit_id": 1,
    "measure_unit": "Unidade",
    "measure_unit__code": "UNI",
    "product_group_id": null,
    "product_group": "",
    "product_section_id": null,
    "product_section": "",
    "supplier_id": null,
    "supplier": "",
    "use_serial_numbers": false,
    "has_lots": false,
    "is_obsolete": false,
    "obs": "",
    "prices": [
        {
            "price_line_id": 1,
            "price_line": "Preço de Venda 1",
            "unit_price": 100.0,
            "unit_price_tax_inc": 123.0
        }
    ],
    "alt_codes": [],
    ...
}

Criar Produto /product/new POST

Criar um novo produto.

Parâmetros Extra  
unit_price_#

Preço Unitário # decimal

Permite definir até 5 preços unitários de venda do produto no momento da criação. '#' pode tomar valores entre 1 e 5 e será associado à linha de preços com o mesmo índice.
Fornecer um valor ao campo, por exemplo, unit_price_1 não requer que o valor de unit_price_tax_inc_1 seja também fornecido. Supondo que usa, por exemplo, 3 linhas de preços distintas, fornecer um valor no campo unit_price_4 não terá qualquer efeito.

unit_price_tax_inc_#

Preço Unitário com IVA # decimal

Permite definir até 5 preços unitários (com IVA) de venda do produto no momento da criação. '#' pode tomar valores entre 1 e 5 e será associado à linha de preços com o mesmo índice.
Fornecer um valor ao campo, por exemplo, unit_price_tax_inc_1 não requer que o valor de unit_price_1 seja também fornecido. Supondo que usa, por exemplo, 2 linhas de preços distintas, fornecer um valor no campo unit_price_tax_inc_3 não terá qualquer efeito.

$ curl -X POST https://www.cloudinvoice.net/v3/product/new/
    -d '{
        "code": "SAMPLE",
        "description": "Produto Exemplo",
        "family": 1,
        "product_type": 131,
        "do_stock_management": true,
        "can_have_negative_stock": true,
        "vat_tax": 1,
        "unit_price_1": 2.35
    }'
{
    "id": 30,
    "code": "SAMPLE",
    "description": "Produto Exemplo",
    "short_description": "Produto Exemplo",
    "family_id": 1,
    "family": "Família 1 (FAM1)",
    "sub_family_id": null,
    "sub_family": "",
    "product_type": 131,
    "product_type_saft": 3271,
    "product_category": 211,
    "bar_code_type": 151,
    "bar_code": null,
    "vat_tax_id": 1,
    "vat_tax": "Taxa Normal",
    "vat_tax_rate": 23.0,
    "vat_exemption_id": null,
    "unit_price": 2.35,
    "unit_price_tax_inc": 2.8905,
    "last_cost_price": 0.0,
    "average_cost_price": 0.0,
    "profit_margin": 0.0,
    "do_stock_management": true,
    "can_have_negative_stock": true,
    "physical_qty": 0.0,
    "global_physical_qty": 0.0,
    "location_physical_qty": 0.0,
    "total_entry_qty": 0.0,
    "total_exit_qty": 0.0,
    "measure_unit_id": 1,
    "measure_unit": "Unidade",
    "measure_unit__code": "UNI",
    "product_group_id": null,
    "product_group": "",
    "product_section_id": null,
    "product_section": "",
    "supplier_id": null,
    "supplier": "",
    "use_serial_numbers": false,
    "has_lots": false,
    "is_obsolete": false,
    "obs": "",
    "prices": [
        {
            "price_line_id": 1,
            "price_line": "Preço de Venda 1",
            "unit_price": 2.35,
            "unit_price_tax_inc": 2.8905
        }
    ],
    "alt_codes": [],
    ...
}

Obter Produto /product/<id> GET

Obter informação de um produto a partir do seu ID.

$ curl https://www.cloudinvoice.net/v3/product/1/
{
    "id": 1,
    "code": "PROD1",
    "description": "Produto Standard 1",
    "short_description": "Produto Standard 1",
    "family_id": 1,
    "family": "Família 1 (FAM1)",
    "sub_family_id": null,
    "sub_family": "",
    "product_type": 131,
    "product_type_saft": 3271,
    "product_category": 211,
    "bar_code_type": 153,
    "bar_code": "2000000000015",
    "vat_tax_id": 1,
    "vat_tax": "Taxa Normal",
    "vat_tax_rate": 23.0,
    "vat_exemption_id": null,
    "unit_price": 100.0,
    "unit_price_tax_inc": 123.0,
    "last_cost_price": 0.0,
    "average_cost_price": 0.0,
    "profit_margin": 0.0,
    "do_stock_management": true,
    "can_have_negative_stock": true,
    "physical_qty": 9.0,
    "global_physical_qty": 9.0,
    "location_physical_qty": 9.0,
    "total_entry_qty": 0.0,
    "total_exit_qty": 1.0,
    "measure_unit_id": 1,
    "measure_unit": "Unidade",
    "measure_unit__code": "UNI",
    "product_group_id": null,
    "product_group": "",
    "product_section_id": null,
    "product_section": "",
    "supplier_id": null,
    "supplier": "",
    "use_serial_numbers": false,
    "has_lots": false,
    "is_obsolete": false,
    "obs": "",
    "prices": [
        {
            "price_line_id": 1,
            "price_line": "Preço de Venda 1",
            "unit_price": 100.0,
            "unit_price_tax_inc": 123.0
        }
    ],
    "alt_codes": [],
    ...
}

Alterar Produto /product/<pk>/update POST

Alterar valores do produto.

Parâmetros Extra  
is_obsolete

Obsoleto bool

Default: false

$ curl -X POST https://www.cloudinvoice.net/v3/product/30/update/
    -d '{
        "bar_code_type": 152,
        "bar_code": "5605566000126"
    }'
{
    "id": 30,
    "code": "SAMPLE",
    "description": "Produto Exemplo",
    "short_description": "Produto Exemplo",
    "family_id": 1,
    "family": "Família 1 (FAM1)",
    "sub_family_id": null,
    "sub_family": "",
    "product_type": 131,
    "product_type_saft": 3271,
    "product_category": 211,
    "bar_code_type": 152,
    "bar_code": "5605566000126",
    "vat_tax_id": 1,
    "vat_tax": "Taxa Normal",
    "vat_tax_rate": 23.0,
    "vat_exemption_id": null,
    "unit_price": 2.35,
    "unit_price_tax_inc": 2.8905,
    "last_cost_price": 0.0,
    "average_cost_price": 0.0,
    "profit_margin": 0.0,
    "do_stock_management": true,
    "can_have_negative_stock": true,
    "physical_qty": 0.0,
    "global_physical_qty": 0.0,
    "location_physical_qty": 0.0,
    "total_entry_qty": 0.0,
    "total_exit_qty": 0.0,
    "measure_unit_id": 1,
    "measure_unit": "Unidade",
    "measure_unit__code": "UNI",
    "product_group_id": null,
    "product_group": "",
    "product_section_id": null,
    "product_section": "",
    "supplier_id": null,
    "supplier": "",
    "use_serial_numbers": false,
    "has_lots": false,
    "is_obsolete": false,
    "obs": ""
    ...
}

Informação de Stocks de Produto /product/<id>/stocks GET

Obter informação relativo aos stocks de um produto.

$ curl https://www.cloudinvoice.net/v3/product/1/stocks/
{
    "company_code": "demo",
    "product": "PROD1 - Produto Standard 1",
    "physical_qty": 10.0
    "warehouses": [
        {
            "id": 1,
            "description": "Armazém 1",
            "physical_qty": 10.0,
            "available_qty": 10.0,
            "cust_ordered_qty": 0.0
        }
    ]
}

Tabelas de Impostos #

Listar Impostos /taxes GET

Fornece uma lista de todos os impostos existentes.

$ curl https://www.cloudinvoice.net/v3/taxes/
[
    {
        "id": 1,
        "code": 1,
        "description": "Taxa Normal",
        "tax_rate": 23.0,
        "tax_exemption__description": null
    },
    {
        "id": 2,
        "code": 2,
        "description": "Taxa Intermédia",
        "tax_rate": 13.0,
        "tax_exemption__description": null
    },
    {
        "id": 3,
        "code": 3,
        "description": "Taxa Reduzida",
        "tax_rate": 6.0,
        "tax_exemption__description": null
    },
    ...
]

Linhas de Preços #

Listar Linhas de Preços /price_lines GET

Fornece uma lista de todas as linhas de preços disponíveis.

$ curl https://www.cloudinvoice.net/v3/price_lines/
[
    {
        "id": 1,
        "code": 1,
        "description": "Preço de Venda 1",
        "price_line_type": 271,
        "is_reseller_price": false
    },
    {
        "id": 2,
        "code": 2,
        "description": "Preço de Venda 2",
        "price_line_type": 271,
        "is_reseller_price": false
    },
    {
        "id": 3,
        "code": 3,
        "description": "Preço de Venda 3",
        "price_line_type": 271,
        "is_reseller_price": false
    },
    ...
]

Unidades de Medida #

Listar Unidades de Medida /measure_units GET

Fornece uma lista de todas as unidades de medida existentes.

$ curl https://www.cloudinvoice.net/v3/measure_units/
[
    {
        "id": 1,
        "code": "UNI",
        "description": "Unidade"
    },
    {
        "id": 7,
        "code": "KG",
        "description": "Kilograma"
    },
    {
        "id": 22,
        "code": "MT",
        "description": "Metro"
    },
    ...
]

Formas de Pagamento #

Listar Formas de Pagamento /payment_methods GET

Fornece uma lista de todas as formas de pagamento disponíveis.

$ curl https://www.cloudinvoice.net/v3/payment_methods/
[
    {
        "id": 1,
        "code": 1,
        "description": "Dinheiro"
    }, {
        "id": 2,
        "code": 2,
        "description": "Cheque bancário"
    }, {
        "id": 3,
        "code": 3,
        "description": "Multibanco"
    },
    ...
]

Países #

Listar Países /countries GET

Fornece uma lista de todos os países existentes.

$ curl https://www.cloudinvoice.net/v3/countries/
[
    {
        "id": 1,
        "code": "PT",
        "country_name": "Portugal",
        "is_eu": true
    },
    {
        "id": 2,
        "code": "ES",
        "country_name": "Espanha",
        "is_eu": true
    },
    {
        "id": 3,
        "code": "FR",
        "country_name": "França",
        "is_eu": true
    },
    ...
]

Procurar País /country-seek/<code> GET

Procurar país por código.

$ curl https://www.cloudinvoice.net/v3/country-seek/PT/
{
    "id": 1,
    "code": "PT",
    "country_name": "Portugal",
    "is_eu": true
}

API - Documentos #

Documentos de Venda #

Nova Documento de Venda /sale/new POST

Criar um novo documento de venda.

Parâmetros  
document_nature

Natureza do Documento int

Pode tomar os valores:

  • 301 - Factura
  • 302 - Factura Simplificada
  • 303 - Factura-Recibo
  • 321 - Guia de Remessa
  • 322 - Guia de Transporte
  • 351 - Nota de Encomenda

Default: Factura

party_id

Cliente int

Relação com o campo 'id' da tabela 'Clientes'.

O id do cliente pode ser logo fornecido na criação para assim evitar chamar posteriormente o end-point específico.

details

Linhas do Documento list

Deverá conter uma lista de objectos, sendo que cada objecto poderá conter os parâmetros de uma linha conforme descritos em Linhas de Documentos.

Os dados para criação das linhas podem ser logo fornecidos na criação para assim evitar chamar posteriormente o end-point específico.

payments

Pagamentos list

Deverá conter uma lista de objectos, sendo que cada objecto poderá conter os parâmetros de um pagamento conforme descritos em Pagamentos de Documentos.

Os dados para criação dos pagamentos podem ser logo fornecidos na criação para assim evitar chamar posteriormente o end-point específico.

finalize

Finalizar Documento de Imediato bool

Se pretender finalizar de imediato um documento de pagamento imediato (ex: Factura-Recibo), deverá fornecer dados relativos ao(s) pagamento(s) no campo payments, de forma a que o somatório dos pagamentos seja igual ao valor total do documento. Só assim o mesmo poderá ser finalizado.

Default: false

$ curl -X POST https://www.cloudinvoice.net/v3/sale/new/
    -d '{
        "document_nature": 302,
        "party_id": 2
    }'
{
    "has_document": true,
    "has_last_sale": false,
    "document": {
        "id": 1,
        "document_key": "FSI A01/-1",
        "document_nature": 302,
        "document_name": "Factura Simplificada",
        "document_status": 1201,
        "status_reason": "",
        "document_date": "2020-06-20",
        "document_time": "12:56:47.205",
        "due_date": "2020-06-20",
        "delivery_date": "",
        "is_valued": true,
        "is_converted": false,
        "is_partial_converted": false,
        "origin_document_header_id": null,
        "origin_document_header": "",
        "origin_document_header__document_name": "",
        "emission_reason": "",
        "warehouse_id": 1,
        "warehouse": "Armazém 1",
        "party_id": 2,
        "party_code": 2,
        "party_name": "Client Demo",
        "party_commercial_name": "",
        "party_fiscal_number": "503217239",
        "salesman_id": 1,
        "salesman": "Vendedor 1",
        "price_line_id": 1,
        "price_line": "Preço de Venda 1",
        "base_currency_id": 1,
        "global_discount1": 0.0,
        "payment_method_id": 1,
        "payment_term_id": 1,
        "payment_term": "Pronto Pagamento",
        "currency_id": 1,
        "is_tax_included": true,
        "has_withholding": false,
        "line_details_count": 0,
        "lines_total_quantity": 0.0,
        "total_amount": 0.0,
        "total_gross_amount_currency": 0.0,
        "total_global_discount_currency": 0.0,
        "total_line_discount_currency": 0.0,
        "total_net_amount_currency": 0.0,
        "total_taxes_amount_currency": 0.0,
        "total_amount_currency": 0.0,
        "withholding_amount_currency": 0.0,
        "total_document_amount_currency": 0.0,
        "total_due_amount_currency": 0.0,
        "document__ask_payment_onclose": true,
        "is_paid": false,
        "paid_total_amount_currency": 0.0,
        "can_finalize": false,
        "can_communicate": false,
        "can_communicate_by_webservice": false,
        ...
    }
}

Obter Documento de Venda /sale/<id> GET

Obter informação de um documento de venda a partir do seu ID.

$ curl https://www.cloudinvoice.net/v3/sale/1/
{
    "has_document": true,
    "has_last_sale": false,
    "document": {
        "id": 1,
        "document_key": "FSI A01/-1",
        "document_nature": 302,
        "document_name": "Factura Simplificada",
        "document_status": 1201,
        "status_reason": "",
        "document_date": "2020-06-20",
        "document_time": "12:56:47.205",
        "due_date": "2020-06-20",
        "delivery_date": "",
        "is_valued": true,
        "is_converted": false,
        "is_partial_converted": false,
        "origin_document_header_id": null,
        "origin_document_header": "",
        "origin_document_header__document_name": "",
        "emission_reason": "",
        "warehouse_id": 1,
        "warehouse": "Armazém 1",
        "party_id": 2,
        "party_code": 2,
        "party_name": "Client Demo",
        "party_commercial_name": "",
        "party_fiscal_number": "503217239",
        "salesman_id": 1,
        "salesman": "Vendedor 1",
        "price_line_id": 1,
        "price_line": "Preço de Venda 1",
        "base_currency_id": 1,
        "global_discount1": 0.0,
        "payment_method_id": 1,
        "payment_term_id": 1,
        "payment_term": "Pronto Pagamento",
        "currency_id": 1,
        "is_tax_included": true,
        "has_withholding": false,
        "line_details_count": 0,
        "lines_total_quantity": 0.0,
        "total_amount": 0.0,
        "total_gross_amount_currency": 0.0,
        "total_global_discount_currency": 0.0,
        "total_line_discount_currency": 0.0,
        "total_net_amount_currency": 0.0,
        "total_taxes_amount_currency": 0.0,
        "total_amount_currency": 0.0,
        "withholding_amount_currency": 0.0,
        "total_document_amount_currency": 0.0,
        "total_due_amount_currency": 0.0,
        "document__ask_payment_onclose": true,
        "is_paid": false,
        "paid_total_amount_currency": 0.0,
        "can_finalize": false,
        "can_communicate": false,
        "can_communicate_by_webservice": false,
        ...
    }
}

Alterar Documento: Definir Cliente /sale/<id>/select-customer POST

Definir cliente a usar no documento. O cliente pode afectar valores do documento como isenção de IVA, retenção na fonte, linha de preços, desconto global, entre outros.

Parâmetros  
party_id

Cliente int

Relação com o campo 'id' da tabela 'Clientes'.

Preenchimento Obrigatório

curl -X POST https://www.cloudinvoice.net/v3/sale/1/select-customer/
    -d '{
        "party_id": 1
    }'
{
    "has_document": true,
    "has_last_sale": false,
    "document": {
        "id": 1,
        "document_key": "FSI A01/-1",
        "document_nature": 302,
        "document_name": "Factura Simplificada",
        "document_status": 1201,
        "status_reason": "",
        "party_id": 1,
        "party_code": 1,
        "party_name": "",
        "party_commercial_name": "",
        "party_fiscal_number": "999999990",
        "price_line_id": 1,
        "price_line": "Preço de Venda 1",
        "global_discount1": 0.0,
        "has_withholding": false,
        ...
    }
}

Alterar Documento: Definir NIF /sale/<id>/set-nif POST

Definir número de identificação fiscal, aplicável quando o cliente actual é o Consumidor Final genérico.
Se existir uma ficha de cliente com o NIF que introduziu, o cliente do documento será substituído, caso contrário, será usado o cliente Consumidor Final com o NIF introduzido.

Parâmetros  
party_fiscal_number

Número de Identificação Fiscal string

Preenchimento Obrigatório

curl -X POST https://www.cloudinvoice.net/v3/sale/1/set-nif/
    -d '{
        "party_fiscal_number": "123456789"
    }'
{
    "has_document": true,
    "has_last_sale": false,
    "document": {
        "id": 1,
        "document_key": "FSI A01/-1",
        "document_nature": 302,
        "document_name": "Factura Simplificada",
        "document_status": 1201,
        "status_reason": "",
        "party_id": 1,
        "party_code": 1,
        "party_name": "",
        "party_commercial_name": "",
        "party_fiscal_number": "123456789",
        "price_line_id": 1,
        "price_line": "Preço de Venda 1",
        "global_discount1": 0.0,
        "has_withholding": false,
        ...
    }
}

Alterar Documento: Preços com IVA Incluído /sale/<id>/set-is-tax-included POST

Alterar documento para que os valores sejam mostrados com ou sem IVA incluído.

Parâmetros  
is_tax_included

Preço Unit c/IVA bool

Default: false

curl -X POST https://www.cloudinvoice.net/v3/sale/1/set-is-tax-included/
    -d '{
        "is_tax_included": false
    }'
{
    "has_document": true,
    "has_last_sale": false,
    "document": {
        "id": 1,
        "document_key": "FSI A01/-1",
        "document_nature": 302,
        "document_name": "Factura Simplificada",
        "document_status": 1201,
        "is_valued": true,
        "is_tax_included": false,
        "line_details_count": 0,
        "lines_total_quantity": 0.0,
        "total_amount": 0.0,
        "can_finalize": false,
        ...
    }
}

Alterar Documento: Definir Desconto Global /sale/<id>/set-global-discount1 POST

Alterar desconto global aplicado ao documento.

Parâmetros  
global_discount1

Desconto Global decimal

Valores: entre 0 e 100

curl -X POST https://www.cloudinvoice.net/v3/sale/1/set-global-discount1/
    -d '{
        "global_discount1": 20.0
    }'
{
    "has_document": true,
    "has_details": true,
    "document": {
        "id": 1,
        "document_key": "FSI A01/-1",
        "document_nature": 302,
        "document_name": "Factura Simplificada",
        "document_status": 1201,
        "is_valued": true,
        "is_tax_included": true,
        "line_details_count": 1,
        "lines_total_quantity": 1.0,
        "global_discount1": 20.0,
        "total_amount": 123.0,
        "total_gross_amount_currency": 123.0,
        "total_global_discount_currency": 20.0,
        "total_line_discount_currency": 0.0,
        "total_net_amount_currency": 80.0,
        "total_taxes_amount_currency": 18.4,
        "total_amount_currency": 98.4,
        "total_document_amount_currency": 98.4,
        "total_due_amount_currency": 98.4,
        "can_finalize": true,
        ...
    },
    "details": [
        {
            "id": 1,
            "line_number": 1,
            "line_subitem": 0,
            "code": "PROD1",
            "short_description": "Produto Standard 1",
            "base_qty": 1.0,
            "base_qty_unit": "1.000 UNI",
            "measure_unit_id": 1,
            "measure_unit__code": "UNI",
            "line_unit_value": 123.0,
            "line_discount1": 0.0,
            "line_discount2": 0.0,
            "use_serial_number": false,
            "has_lots": false,
            "lot_number": "",
            "gross_unit_price_currency": 123.0,
            "total_net_amount_currency": 80.0,
            "total_amount_currency": 98.4,
            ...
        }
    ]
}

Limpar Linhas /sale/<id>/delete-all POST

Apagar todas as linhas do documento.

$ curl -X POST https://www.cloudinvoice.net/v3/sale/1/delete-all/
{
    "has_document": true,
    "has_last_sale": false,
    "document": {
        "id": 1,
        "document_key": "FSI A01/-1",
        "document_nature": 302,
        "document_name": "Factura Simplificada",
        "document_status": 1201,
        "status_reason": "",
        "document_date": "2020-06-20",
        "document_time": "12:56:47.205",
        "due_date": "2020-06-20",
        "delivery_date": "",
        "is_valued": true,
        "is_converted": false,
        "is_partial_converted": false,
        "origin_document_header_id": null,
        "origin_document_header": "",
        "origin_document_header__document_name": "",
        "emission_reason": "",
        "warehouse_id": 1,
        "warehouse": "Armazém 1",
        "party_id": 2,
        "party_code": 2,
        "party_name": "Client Demo",
        "party_commercial_name": "",
        "party_fiscal_number": "503217239",
        "salesman_id": 1,
        "salesman": "Vendedor 1",
        "price_line_id": 1,
        "price_line": "Preço de Venda 1",
        "base_currency_id": 1,
        "global_discount1": 0.0,
        "payment_method_id": 1,
        "payment_term_id": 1,
        "payment_term": "Pronto Pagamento",
        "currency_id": 1,
        "is_tax_included": true,
        "has_withholding": false,
        "line_details_count": 0,
        "lines_total_quantity": 0.0,
        "total_amount": 0.0,
        "total_gross_amount_currency": 0.0,
        "total_global_discount_currency": 0.0,
        "total_line_discount_currency": 0.0,
        "total_net_amount_currency": 0.0,
        "total_taxes_amount_currency": 0.0,
        "total_amount_currency": 0.0,
        "withholding_amount_currency": 0.0,
        "total_document_amount_currency": 0.0,
        "total_due_amount_currency": 0.0,
        "document__ask_payment_onclose": true,
        "is_paid": false,
        "paid_total_amount_currency": 0.0,
        "can_finalize": false,
        "can_communicate": false,
        "can_communicate_by_webservice": false,
        ...
    }
}

Cancelar Documento de Venda /sale/<id>/cancel POST

Cancelar um documento de venda. Ao ser cancelado, um documento é completamente apagado do sistema, sendo irrecuperável.
Um documento apenas pode ser cancelado até ao momento em que é finalizado. Após a finalização, terá de usar a anulação.

$ curl -X POST https://www.cloudinvoice.net/v3/sale/1/cancel/
{
    "id": 1
}

Finalizar Documento de Venda /sale/<id>/finalize POST

Finalizar documento de venda.
Documentos de venda, por norma, requerem a existência de linhas para poderem ser finalizados com sucesso.
No caso de documentos de pagamento imediato (ex: Factura-Recibo), terão de existir também pagamentos da totalidade do documento.

$ curl -X POST https://www.cloudinvoice.net/v3/sale/1/finalize/
{
    "instance": {
        "id": 1,
        "document_key": "FSI A01/1",
        "document_name": "Factura Simplificada",
        "party_id": 2,
        "party_name": "Client Demo",
        "document_status": 1202
    }
}

Anular Documento de Venda /sale/<id>/annul POST

Anular documento de venda.

Parâmetros  
status_reason

Motivo da Anulação decimal

Preenchimento Obrigatório

curl -X POST https://www.cloudinvoice.net/v3/sale/1/annul/
    -d '{
        "status_reason": "Por uma boa razão!"
    }'
{
    "has_document": true,
    "has_details": true,
    "document": {
        "id": 1,
        "document_key": "FSI A01/1",
        "document_nature": 302,
        "document_name": "Factura Simplificada",
        "document_status": 1203,
        "status_reason": "Por uma boa razão!",
        "is_valued": true,
        "is_tax_included": true,
        ...
  },
  ...
}

Linhas de Documentos #

Parâmetros

code

Código string

Identificador do produto a usar na linha. 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.

Preenchimento Obrigatório

description

Descrição string

Esta valor, se preenchido, vai sobrepor-se à descrição na ficha do produto apenas na presente linha.

base_qty

Quantidade decimal

Default: 1

line_discount1

Desconto de Linha #1 decimal

Valores: entre 0 e 100

line_discount2

Desconto de Linha #2 decimal

Valores: entre 0 e 100

Listar Linhas de Documento /sale/<document_id>/details GET

Listar linhas de um documento.

curl https://www.cloudinvoice.net/v3/sale/1/details/
{
    "has_details": true,
    "details": [
        {
            "id": 1,
            "line_number": 1,
            "line_subitem": 0,
            "code": "PROD1",
            "short_description": "Produto Standard 1",
            "base_qty": 1.0,
            "base_qty_unit": "1.000 UNI",
            "measure_unit_id": 1,
            "measure_unit__code": "UNI",
            "line_unit_value": 100.0,
            "line_discount1": 0.0,
            "line_discount2": 0.0,
            "use_serial_number": false,
            "has_lots": false,
            "lot_number": "",
            "gross_unit_price_currency": 100.0,
            "total_net_amount_currency": 100.0,
            "total_amount_currency": 123.0,
            ...
        }
    ]
}

Criar Linha(s) em Documento /sale/<document_id>/details/add POST

Criar linha(s) num documento. A resposta contém também informação actualizada do documento.

$ curl -X POST https://www.cloudinvoice.net/v3/sale/1/detail/add/
    -d '{
        "details":[
            {
                "code": "PROD1",
                "base_qty": 1
            },
            {
                "code": "PROD2",
                "base_qty": 2,
                "line_unit_value": 2.20
            }
        ]
    }'
{
    "has_document": true,
    "has_details": true,
    "document": {
        "id": 1,
        "document_key": "FSI A01/-1",
        "document_nature": 302,
        "document_name": "Factura Simplificada",
        "document_status": 1201,
        "status_reason": "",
        "document_date": "2020-06-20",
        "document_time": "12:56:47.205",
        "is_valued": true,
        "is_tax_included": true,
        "line_details_count": 2,
        "lines_total_quantity": 3.0,
        "total_amount": 127.4,
        "total_gross_amount_currency": 127.4,
        "total_global_discount_currency": 0.0,
        "total_line_discount_currency": 0.0,
        "total_net_amount_currency": 103.5772357724,
        "total_taxes_amount_currency": 23.8227642276,
        "total_amount_currency": 127.4,
        "total_document_amount_currency": 127.4,
        "total_due_amount_currency": 127.4,
        "can_finalize": true,
        ...
    },
    "details": [
        {
            "id": 1,
            "line_number": 1,
            "line_subitem": 0,
            "code": "PROD1",
            "short_description": "Produto Standard 1",
            "base_qty": 1.0,
            "base_qty_unit": "1.000 UNI",
            "measure_unit_id": 1,
            "measure_unit__code": "UNI",
            "line_unit_value": 123.0,
            "line_discount1": 0.0,
            "line_discount2": 0.0,
            "use_serial_number": false,
            "has_lots": false,
            "lot_number": "",
            "gross_unit_price_currency": 123.0,
            "total_net_amount_currency": 100.0,
            "total_amount_currency": 123.0,
            ...
        },
        {
            "id": 2,
            "line_number": 2,
            "line_subitem": 0,
            "code": "PROD2",
            "short_description": "Produto Standard 2",
            "base_qty": 2.0,
            "base_qty_unit": "2.000 UNI",
            "measure_unit_id": 1,
            "measure_unit__code": "UNI",
            "line_unit_value": 2.2,
            "line_discount1": 0.0,
            "line_discount2": 0.0,
            "use_serial_number": false,
            "has_lots": false,
            "lot_number": "",
            "gross_unit_price_currency": 2.2,
            "total_net_amount_currency": 3.5772357724,
            "total_amount_currency": 4.4,
            ...
        }
    ]
}

Alterar Linha de Documento /sale/<document_id>/details/<id>/update POST

Alterar linha de um documento. A resposta contém também informação actualizada do documento.

curl https://www.cloudinvoice.net/v3/sale/1/detail/2/update/
    -d '{
        "line_discount1": 5.0
    }'
{
    "has_document": true,
    "has_details": true,
    "document": {
        "id": 1,
        "document_key": "FSI A01/-1",
        "document_nature": 302,
        "document_name": "Factura Simplificada",
        "document_status": 1201,
        "status_reason": "",
        "document_date": "2020-06-20",
        "document_time": "12:56:47.205",
        "is_valued": true,
        "is_tax_included": true,
        "line_details_count": 2,
        "lines_total_quantity": 3.0,
        "total_amount": 127.18,
        "total_gross_amount_currency": 127.18,
        "total_global_discount_currency": 0.0,
        "total_line_discount_currency": 0.22,
        "total_net_amount_currency": 103.3983739837,
        "total_taxes_amount_currency": 23.7816260163,
        "total_amount_currency": 127.18,
        "total_document_amount_currency": 127.18,
        "total_due_amount_currency": 127.18,
        "can_finalize": true,
        ...
    },
    "details": [
        {
            "id": 1,
            "line_number": 1,
            "line_subitem": 0,
            "code": "PROD1",
            "short_description": "Produto Standard 1",
            "base_qty": 1.0,
            "base_qty_unit": "1.000 UNI",
            "measure_unit_id": 1,
            "measure_unit__code": "UNI",
            "line_unit_value": 123.0,
            "line_discount1": 0.0,
            "line_discount2": 0.0,
            "use_serial_number": false,
            "has_lots": false,
            "lot_number": "",
            "gross_unit_price_currency": 123.0,
            "total_net_amount_currency": 100.0,
            "total_amount_currency": 123.0,
            ...
        },
        {
            "id": 2,
            "line_number": 2,
            "line_subitem": 0,
            "code": "PROD2",
            "short_description": "Produto Standard 2",
            "base_qty": 2.0,
            "base_qty_unit": "2.000 UNI",
            "measure_unit_id": 1,
            "measure_unit__code": "UNI",
            "line_unit_value": 2.2,
            "line_discount1": 5.0,
            "line_discount2": 0.0,
            "use_serial_number": false,
            "has_lots": false,
            "lot_number": "",
            "gross_unit_price_currency": 2.2,
            "total_net_amount_currency": 3.3983739837,
            "total_amount_currency": 4.18,
            ...
        }
    ]
}

Apagar Linha de Documento /sale/<document_id>/details/<id>/delete POST

Apagar linha de um documento. A resposta contém também informação actualizada do documento.
Se o que pretende é apagar todas as linhas do documento de uma vez, pode ver em Limpar Linhas do Documento

https://www.cloudinvoice.net/v3/sale/1/detail/2/delete/
{
    "has_document": true,
    "has_details": true,
    "document": {
        "id": 1,
        "document_key": "FSI A01/-1",
        "document_nature": 302,
        "document_name": "Factura Simplificada",
        "document_status": 1201,
        "status_reason": "",
        "document_date": "2020-06-20",
        "document_time": "12:56:47.205",
        "is_valued": true,
        "is_tax_included": true,
        "line_details_count": 1,
        "lines_total_quantity": 1.0,
        "total_amount": 123.0,
        "total_gross_amount_currency": 123.0,
        "total_global_discount_currency": 0.0,
        "total_line_discount_currency": 0.0,
        "total_net_amount_currency": 100.0,
        "total_taxes_amount_currency": 23.0,
        "total_amount_currency": 123.0,
        "total_document_amount_currency": 123.0,
        "total_due_amount_currency": 123.0,
        "can_finalize": true,
        ...
    },
    "details": [
        {
            "id": 1,
            "line_number": 1,
            "line_subitem": 0,
            "code": "PROD1",
            "short_description": "Produto Standard 1",
            "base_qty": 1.0,
            "base_qty_unit": "1.000 UNI",
            "measure_unit_id": 1,
            "measure_unit__code": "UNI",
            "line_unit_value": 123.0,
            "line_discount1": 0.0,
            "line_discount2": 0.0,
            "use_serial_number": false,
            "has_lots": false,
            "lot_number": "",
            "gross_unit_price_currency": 123.0,
            "total_net_amount_currency": 100.0,
            "total_amount_currency": 123.0,
            ...
        }
    ]
}

Pagamentos de Documentos #

Documentos de cobrança imediata, como Factura-Recibo ou Factura Simplificada, requerem que, para que possam ser finalizados com sucesso, existam pagamentos cujo somatório seja igual ao total do documento.

Parâmetros

payment_method

Forma de Pagamento int

Relação com o campo 'id' da tabela 'Métodos de Pagamento'.

Preenchimento Obrigatório

amount_received_currency

Valor do Pagamento decimal

Preenchimento Obrigatório

payment_doc_reference

Referência do Pagamento string

O preenchimento deste campo é obrigatório em alguns métodos de pagamento.

payment_doc_date

Data do Documento de Pagamento date

O preenchimento deste campo é obrigatório em alguns métodos de pagamento.

Listar Pagamentos de Documento /sale/<document_id>/payments GET

Listar pagamentos de um documento.

$ curl https://www.cloudinvoice.net/v3/sale/1/payments/
[
    {
        "id": 1,
        "payment_method_id": 1,
        "payment_method": "Dinheiro",
        "payment_method__code": 1,
        "amount_received_currency": 50.0,
        "payment_doc_reference": "",
        "payment_doc_date": "",
    },
    {
        "id": 2,
        "payment_method_id": 4,
        "payment_method": "Visa",
        "payment_method__code": 4,
        "amount_received_currency": 73.0,
        "payment_doc_reference": "",
        "payment_doc_date": "",
    }
]

Criar Pagamento de Documento /sale/<document_id>/payment/add POST

Criar pagamento de um documento. A resposta contém também informação actualizada do documento.

curl -X POST https://www.cloudinvoice.net/v3/sale/1/payment/add/
    -d '{
        "payment_method": 1,
        "amount_received_currency": 50.0
    }'
{
    "has_document": true,
    "document": {
        "id": 1,
        "document_key": "FSI A01/-1",
        "document_nature": 302,
        "document_name": "Factura Simplificada",
        "document_status": 1201,
        "status_reason": "",
        "document_date": "2020-06-20",
        "document_time": "12:56:47.205",
        "is_valued": true,
        "is_tax_included": true,
        "is_paid": false,
        "line_details_count": 1,
        "lines_total_quantity": 1.0,
        "total_amount": 123.0,
        "total_gross_amount_currency": 123.0,
        "total_global_discount_currency": 0.0,
        "total_line_discount_currency": 0.0,
        "total_net_amount_currency": 100.0,
        "total_taxes_amount_currency": 23.0,
        "total_amount_currency": 123.0,
        "total_document_amount_currency": 123.0,
        "paid_total_amount_currency": 50.0,
        "total_due_amount_currency": 73.0,
        "can_finalize": true,
        ...
    },
    "payments": [
        {
            "id": 1,
            "payment_method_id": 1,
            "payment_method": "Dinheiro",
            "payment_method__code": 1,
            "amount_received_currency": 50.0,
            "payment_doc_reference": "",
            "payment_doc_date": ""
        }
    ],
    ...
}

Alterar Pagamento de Documento /sale/<document_id>/payment/<id>/update POST

Alterar pagamento de um documento. A resposta contém também informação actualizada do documento.

curl -X POST https://www.cloudinvoice.net/v3/sale/1/payment/update/
    -d '{
        "amount_received_currency": 123.0
    }'
{
    "has_document": true,
    "document": {
        "id": 1,
        "document_key": "FSI A01/-1",
        "document_nature": 302,
        "document_name": "Factura Simplificada",
        "document_status": 1201,
        "status_reason": "",
        "document_date": "2020-06-20",
        "document_time": "12:56:47.205",
        "is_valued": true,
        "is_tax_included": true,
        "is_paid": false,
        "line_details_count": 1,
        "lines_total_quantity": 1.0,
        "total_amount": 123.0,
        "total_gross_amount_currency": 123.0,
        "total_global_discount_currency": 0.0,
        "total_line_discount_currency": 0.0,
        "total_net_amount_currency": 100.0,
        "total_taxes_amount_currency": 23.0,
        "total_amount_currency": 123.0,
        "total_document_amount_currency": 123.0,
        "paid_total_amount_currency": 123.0,
        "total_due_amount_currency": 0.0,
        "can_finalize": true,
        ...
    },
    "payments": [
        {
            "id": 1,
            "payment_method_id": 1,
            "payment_method": "Dinheiro",
            "payment_method__code": 1,
            "amount_received_currency": 123.0,
            "payment_doc_reference": "",
            "payment_doc_date": ""
        }
    ],
    ...
}

Apagar Pagamento de Documento /sale/<document_id>/payment/<id>/delete POST

Apagar pagamento de um documento. A resposta contém também informação actualizada do documento.

$ curl -X POST https://www.cloudinvoice.net/v3/sale/1/payment/2/delete/
{
    "has_document": true,
    "document": {
        "id": 1,
        "document_key": "FSI A01/-1",
        "document_nature": 302,
        "document_name": "Factura Simplificada",
        "document_status": 1201,
        "status_reason": "",
        "document_date": "2020-06-20",
        "document_time": "12:56:47.205",
        "is_valued": true,
        "is_tax_included": true,
        "is_paid": false,
        "line_details_count": 1,
        "lines_total_quantity": 1.0,
        "total_amount": 123.0,
        "total_gross_amount_currency": 123.0,
        "total_global_discount_currency": 0.0,
        "total_line_discount_currency": 0.0,
        "total_net_amount_currency": 100.0,
        "total_taxes_amount_currency": 23.0,
        "total_amount_currency": 123.0,
        "total_document_amount_currency": 123.0,
        "paid_total_amount_currency": 50.0,
        "total_due_amount_currency": 73.0,
        "can_finalize": true,
        ...
    },
    "payments": [
        {
            "id": 1,
            "payment_method_id": 1,
            "payment_method": "Dinheiro",
            "payment_method__code": 1,
            "amount_received_currency": 50.0,
            "payment_doc_reference": "",
            "payment_doc_date": ""
        }
    ],
    ...
}

Outras Acções #

Emitir Documento de Venda /guide/<id>/emit-sale POST

Emitir documento de venda a partir de guia ou encomenda.

Parâmetros  
target_document_nature

Natureza do Documento de Destino int

Pode tomar os valores:

  • 301 - Factura
  • 302 - Factura Simplificada
  • 303 - Factura-Recibo

Default: Factura

details

Linhas do Documento de Origem a Emitir list

Deverá conter uma lista de objectos, sendo que cada objecto deverá conter o id da linha de origem.
Pode também incluir no objecto valores para os seguintes campos, para emissões parciais:

  • base_qty - não deverá ultrapassar o valor da origem
  • line_unit_value - não deverá ultrapassar o valor da origem
  • line_discount1 - valores entre 0 e 100
  • line_discount2 - valores entre 0 e 100

Preenchimento Obrigatório

curl -X POST https://www.cloudinvoice.net/v3/guide/1/emit-sale/
    -d '{
        "target_document_nature": 303,
         "details": [
            {
                "id": 1,
                "description": "Produto Exemplo"
            }
        ]
    }'
{
    "id": 2
}

Emitir Recibo /sale/<id>/emit-receipt POST

Emitir recibo a partir de documento de venda.
A resposta contém o id do novo documento.

Parâmetros  
total_received_amount

Valor a Liquidar decimal

Preenchimento Obrigatório

curl -X POST https://www.cloudinvoice.net/v3/guide/1/emit-receipt/
    -d '{
        "total_received_amount": 50.0
    }'
{
    "id": 1
}

Imprimir Documento /sale/<id>/print POST

Imprimir documento. Entenda-se por 'imprimir' o gerar do documento em formato PDF para impressão.

Parâmetros  
print_mode

Modo de Impressão string

curl -X POST https://www.cloudinvoice.net/v3/sale/1/print/
    -d '{
        "print_mode": "browser"
    }'
{
    "is_document": true,
    "is_receipt": false,
    "filename": "FS__FSI_A01_1__2020_06_22_1592908727.pdf",
    "report_url": "http://www.cloudinvoice.net/downloads/c3c00f37-a7cb-4b42-b631-be03a2b785c8/download_file/?direct=true&compressed=false"
}

Consultas #

Consultar lista de documentos. /sales GET

Emitir documento de venda a partir de guia ou encomenda. Todas as linhas do documento de origem serão emitidas no documento de destino de forma integral.

$ curl https://www.cloudinvoice.net/v3/sales/
{
    "results": [
        {
            "id": 1,
            "description": "Factura-Recibo",
            "document_id": 3,
            "document_code": "FRE",
            "document_name": "Factura-Recibo",
            "document_nature": 303,
            "document_serie_id": 1,
            "document_serie_code": "A01",
            "document_number": 1,
            "doc_key": "FRE A01/1",
            "document_status": 1202,
            "is_valued": 1,
            "is_converted": 0,
            "party_id": 5,
            "party_code": 5,
            "party_fiscal_number": "999999990",
            "party_name": "John DOE",
            "line_details_count": 3,
            "lines_total_quantity": 3.0,
            "total_amount_raw": 61.8,
            "total_amount_currency_raw": 61.8,
            ...
        },
        {
            "id": 2,
            "description": "Factura",
            "document_id": 1,
            "document_code": "FAC",
            "document_name": "Factura",
            "document_nature": 301,
            "document_serie_id": 1,
            "document_serie_code": "A01",
            "document_number": 1,
            "doc_key": "FAC A01/1",
            "document_status": 1202,
            "is_valued": 1,
            "is_converted": 0,
            "party_id": 2,
            "party_code": 2,
            "party_fiscal_number": "503217239",
            "party_name": "Client Demo",
            "line_details_count": 1,
            "lines_total_quantity": 1.0,
            "total_amount_raw": 123.0,
            "total_amount_currency_raw": 123.0,
            ...
        }
    ],
    "count_total": 2
}

Suporte #

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 desde já que reporte 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. Teremos todo o gosto em ajudar no que for possível.

Changelog #

Versão 1.0 - 24 de Junho 2020
Alterações
Lançamento Inicial