{b% load base_tags %}

Clientes

Um cliente representa uma entidade ao qual pode emitir vendas e gerir contas-correntes.

API - Clientes:

Apresentamos alguns end-points que permitem consultar, criar e editar clientes.

  1. Listar Clientes
  2. Procurar Cliente
  3. Criar Cliente
  4. Obter Clientes
  5. Alterar Cliente
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
language Língua int Relação com o campo 'id' da tabela 'Línguas'
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 código, nome ou número de identificação fiscal (NIF).
O termo de procura search pode conter tanto o código do cliente code, como o NIF fiscal_number ou o nome do cliente customer_name. Para os casos de pesquisa com NIF e nome de cliente, o termo de pesquisa deverá ser precedido do código ISO (alpha2) do país fiscal_country separado por hiffen (ex: "PT-503217239" ou "PT-Client Demo").
A resposta trará um único resultado, mas apenas se for encontrada uma, e apenas uma, combinação exacta do termo de procura.

Importante:
 Como o termo de procura é incluído no URL do pedido, deverá ser feito escape aos caracteres não alfanuméricos, substituindo os espaços por '+' (ex: "PT-Client+Demo"). 

                    
                        $ curl https://www.cloudinvoice.net/v3/customer-seek/1/
                    
                  
                    
                        {
    "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": "",
    ...
}
                    
                  
                    
                        $ 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": "",
    ...
}
                    
                  
                    
                        $ curl https://www.cloudinvoice.net/v3/customer-seek/PT-Cliente+Demo/
                    
                  
                    
                        {
    "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 /customers/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 dados pessoais e fiscais do 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",
    ...
}