API Facturalusa

Introdução

A nossa API é desenvolvida em formato REST, disponibilizamos URL's intuítivos e respostas em formato JSON. Pode experimentar e utilizar a API em modo demo enquanto constroi a sua aplicação. A API key determina se os pedidos efectuados são em ambiente produção ou teste.

Todos os pedidos devem ser feitos com recurso ao método POST.

Alguns valores decimais retornados pela API podem apresentar várias casas decimais, pelo que deve arredondar sempre que necessário a 2 casas decimais.

Autenticação

O Facturalusa utiliza uma API key para autenticar os pedidos. Esta API única pode ser visualizada no backoffice. Todos os pedidos devem enviar o parâmetro api_token. Pedidos onde não conste a autenticação adequada vão dar erro.

Cada plano aplica uma restrição ao limite de pedidos que podem ser realizados num espaço de 24h:

  • Plano Básico: 1000
  • Plano Médio: 2000
  • Plano Grande: 3000
  • Plano Personalizado: a decidir

Certifique-se que se mantêm abaixo deste valor para não ser bloqueado.

Request POST /api/v1/sample
                                    curl --request POST
                                        --url 'https://facturalusa.pt/api/v1/sample'
                                        --header 'Accept: application/json'
                                        --header 'Content-type: application/json'
                                        --body '{"api_token": "value", "param1": "value1"}'
                                

Resposta e erros

Utilizámos os códigos de erros convencionais que indicam se o pedido foi feito ou não com sucesso, mas por norma apenas dois códigos são utilizados: 200 e 403, que indicam, respectivamente, se o pedido foi feito com sucesso ou se foi recusado (por não ter permissões de acesso, por exemplo).

Também podem ser retornados outros códigos de erro, como por exemplo 4xx e 5xx, mas estes são menos comuns por se tratarem de erros internos. Em caso de anomalia por favor contacte-nos.

Em todas as situações a resposta é sempre devolvida em formato JSON e pode variar consoante seja bem sucedido e mal sucedido.

Em caso de erro:
HTTP 403 { status: false, message: ... }
Em caso de sucesso:
HTTP 200 { status: true }
Em caso de sucesso e com devolução de informação:
HTTP 200 { status: true, data: [] }
HTTP 200 { status: true, id: .. }

Caso o plano se encontre expirado, não é possível utilizar a API, sendo sempre devolvido o código 403.

Tabela de possíveis códigos HTTP
200 - OK Pedido executado com sucesso
400 - Bad Request Pedido incorrecto, talvez por falta de parâmetros
401 - Unauthorized A API key disponibilizada não é válida
403 - Forbidden A API key não tem permissões para efectuar o pedido ou parâmetros mal preenchidos
404 - Not Found O endpoint utilizado não se encontra disponível
429 - Too Many Requests Ultrapassou o limite de pedidos que pode fazer
500, 502, 503, 504 - Server Errors Erros internos da aplicação

Biblioteca

Disponibilizamos uma biblioteca em PHP para ajudar na interacção com a API e que pode ser instalada utilizando o Composer.

A documentação da biblioteca pode ser vista no repositório de GitHub https://github.com/Infolusa/php-facturalusa

Instalação & utilização
                                    // Instalação
                                    $ composer require infolusa/php-facturalusa
                                
                                 
                                    // Utilização   
                                    $facturalusa = new \Facturalusa\FacturalusaClient('api_token');
                                    $customer = new \Facturalusa\Customer\Customer($facturalusa);
                                    $customer->list();
                                
                                 
                                    // Resposta
                                    print_r($facturalusa->response());
                                

Países

Quando necessário preencher o campo country em determinados endpoints, este deve conter o nome do país em idioma inglês ou o código ISO universal.

Tabela de países
  • AF - Afghanistan
  • AL - Albania
  • DZ - Algeria
  • AS - American Samoa
  • AD - Andorra
  • AO - Angola
  • AI - Anguilla
  • AQ - Antarctica
  • AG - Antigua and Barbuda
  • AR - Argentina
  • AM - Armenia
  • AW - Aruba
  • AU - Australia
  • AT - Austria
  • AZ - Azerbaijan
  • BS - Bahamas
  • BH - Bahrain
  • BD - Bangladesh
  • BB - Barbados
  • BY - Belarus
  • BE - Belgium
  • BZ - Belize
  • BJ - Benin
  • BM - Bermuda
  • BT - Bhutan
  • BO - Bolivia
  • BA - Bosnia and Herzegovina
  • BW - Botswana
  • BV - Bouvet Island
  • BR - Brazil
  • IO - British Indian Ocean Territory
  • BN - Brunei Darussalam
  • BG - Bulgaria
  • BF - Burkina Faso
  • BI - Burundi
  • KH - Cambodia
  • CM - Cameroon
  • CA - Canada
  • CV - Cape Verde
  • KY - Cayman Islands
  • CF - Central African Republic
  • TD - Chad
  • CL - Chile
  • CN - China
  • CX - Christmas Island
  • CC - Cocos (Keeling) Islands
  • CO - Colombia
  • KM - Comoros
  • CG - Congo
  • CK - Cook Islands
  • CR - Costa Rica
  • CI - Cote D'Ivoire
  • HR - Croatia
  • CU - Cuba
  • CY - Cyprus
  • CZ - Czech Republic
  • DK - Denmark
  • DJ - Djibouti
  • DM - Dominica
  • DO - Dominican Republic
  • TL - East Timor
  • EC - Ecuador
  • EG - Egypt
  • SV - El Salvador
  • GQ - Equatorial Guinea
  • ER - Eritrea
  • EE - Estonia
  • ET - Ethiopia
  • FK - Falkland Islands (Malvinas)
  • FO - Faroe Islands
  • FJ - Fiji
  • FI - Finland
  • FR - France
  • GF - French Guiana
  • PF - French Polynesia
  • TF - French Southern Territories
  • GA - Gabon
  • GM - Gambia
  • GE - Georgia
  • DE - Germany
  • GH - Ghana
  • GI - Gibraltar
  • GR - Greece
  • GL - Greenland
  • GD - Grenada
  • GP - Guadeloupe
  • GU - Guam
  • GT - Guatemala
  • GN - Guinea
  • GW - Guinea-Bissau
  • GY - Guyana
  • HT - Haiti
  • HM - Heard and Mc Donald Islands
  • HN - Honduras
  • HK - Hong Kong
  • HU - Hungary
  • IS - Iceland
  • IN - India
  • ID - Indonesia
  • IR - Iran (Islamic Republic of)
  • IQ - Iraq
  • IE - Ireland
  • IL - Israel
  • IT - Italy
  • JM - Jamaica
  • JP - Japan
  • JO - Jordan
  • KZ - Kazakhstan
  • KE - Kenya
  • KI - Kiribati
  • KP - North Korea
  • KR - Korea, Republic of
  • KW - Kuwait
  • KG - Kyrgyzstan
  • LA - Lao People's Democratic Republic
  • LV - Latvia
  • LB - Lebanon
  • LS - Lesotho
  • LR - Liberia
  • LY - Libyan Arab Jamahiriya
  • LI - Liechtenstein
  • LT - Lithuania
  • LU - Luxembourg
  • MO - Macau
  • MK - FYROM
  • MG - Madagascar
  • MW - Malawi
  • MY - Malaysia
  • MV - Maldives
  • ML - Mali
  • MT - Malta
  • MH - Marshall Islands
  • MQ - Martinique
  • MR - Mauritania
  • MU - Mauritius
  • YT - Mayotte
  • MX - Mexico
  • FM - Micronesia, Federated States of
  • MD - Moldova, Republic of
  • MC - Monaco
  • MN - Mongolia
  • MS - Montserrat
  • MA - Morocco
  • MZ - Mozambique
  • MM - Myanmar
  • NA - Namibia
  • NR - Nauru
  • NP - Nepal
  • NL - Netherlands
  • AN - Netherlands Antilles
  • NC - New Caledonia
  • NZ - New Zealand
  • NI - Nicaragua
  • NE - Niger
  • NG - Nigeria
  • NU - Niue
  • NF - Norfolk Island
  • MP - Northern Mariana Islands
  • NO - Norway
  • OM - Oman
  • PK - Pakistan
  • PW - Palau
  • PA - Panama
  • PG - Papua New Guinea
  • PY - Paraguay
  • PE - Peru
  • PH - Philippines
  • PN - Pitcairn
  • PL - Poland
  • PT - Portugal
  • PR - Puerto Rico
  • QA - Qatar
  • RE - Reunion
  • RO - Romania
  • RU - Russian Federation
  • RW - Rwanda
  • KN - Saint Kitts and Nevis
  • LC - Saint Lucia
  • VC - Saint Vincent and the Grenadines
  • WS - Samoa
  • SM - San Marino
  • ST - Sao Tome and Principe
  • SA - Saudi Arabia
  • SN - Senegal
  • SC - Seychelles
  • SL - Sierra Leone
  • SG - Singapore
  • SK - Slovak Republic
  • SI - Slovenia
  • SB - Solomon Islands
  • SO - Somalia
  • ZA - South Africa
  • GS - South Georgia & South Sandwich Islands
  • ES - Spain
  • LK - Sri Lanka
  • SH - St. Helena
  • PM - St. Pierre and Miquelon
  • SD - Sudan
  • SR - Suriname
  • SJ - Svalbard and Jan Mayen Islands
  • SZ - Swaziland
  • SE - Sweden
  • CH - Switzerland
  • SY - Syrian Arab Republic
  • TW - Taiwan
  • TJ - Tajikistan
  • TZ - Tanzania, United Republic of
  • TH - Thailand
  • TG - Togo
  • TK - Tokelau
  • TO - Tonga
  • TT - Trinidad and Tobago
  • TN - Tunisia
  • TR - Turkey
  • TM - Turkmenistan
  • TC - Turks and Caicos Islands
  • TV - Tuvalu
  • UG - Uganda
  • UA - Ukraine
  • AE - United Arab Emirates
  • GB - United Kingdom
  • US - United States
  • UM - United States Minor Outlying Islands
  • UY - Uruguay
  • UZ - Uzbekistan
  • VU - Vanuatu
  • VA - Vatican City State (Holy See)
  • VE - Venezuela
  • VN - Viet Nam
  • VG - Virgin Islands (British)
  • VI - Virgin Islands (U.S.)
  • WF - Wallis and Futuna Islands
  • EH - Western Sahara
  • YE - Yemen
  • CD - Democratic Republic of Congo
  • ZM - Zambia
  • ZW - Zimbabwe
  • ME - Montenegro
  • RS - Serbia
  • AX - Aaland Islands
  • BQ - Bonaire, Sint Eustatius and Saba
  • CW - Curacao
  • PS - Palestinian Territory, Occupied
  • SS - South Sudan
  • BL - St. Barthelemy
  • MF - St. Martin (French part)
  • IC - Canary Islands
  • AC - Ascension Island (British)
  • XK - Kosovo, Republic of
  • IM - Isle of Man
  • TA - Tristan da Cunha
  • GG - Guernsey
  • JE - Jersey

Isenções de IVA

Quando necessário preencher o campo vat_exemption em determinados endpoints, este deve conter o ID (1, 2, 3, ..) ou o código (M01, M02, M03, ..) da isenção de IVA.

Tabela de isenções de IVA
  • 1 M01 - Artigo 16.º n.º 6 do CIVA (ou similar)
  • 2 M02 - Artigo 6.º do Decreto-Lei n.º 198/90, de 19 de Junho
  • 4 M04 - Isento Artigo 13.º do CIVA (ou similar)
  • 5 M05 - Isento Artigo 14.º do CIVA (ou similar)
  • 6 M06 - Isento Artigo 15.º do CIVA (ou similar)
  • 7 M07 - Isento Artigo 9.º do CIVA (ou similar)
  • 9 M09 - IVA - não confere direito a dedução
  • 10 M10 - IVA - Regime de isenção
  • 11 M11 - Regime particular do tabaco
  • 12 M12 - Regime da margem de lucro – Agências de viagens
  • 13 M13 - Regime da margem de lucro – Bens em segunda mão
  • 14 M14 - Regime da margem de lucro – Objetos de arte
  • 15 M15 - Regime da margem de lucro – Objetos de Coleção e antiguidades
  • 16 M16 - Isento Artigo 14.º do RITI (ou similar)
  • 18 M18 - Sem isenção
  • 20 M19 - Outras isenções
  • 19 M20 - IVA - Regime forfetário
  • 21 M21 - IVA - não confere direito à dedução
  • 22 M25 - Mercadorias à consignação
  • 30 M26 - Isenção de IVA com direito à dedução no cabaz alimentar
  • 23 M30 - IVA - autoliquidação - Artigo 2.º n.º 1 alínea i) do CIVA
  • 24 M31 - IVA - autoliquidação - Artigo 2.º n.º 1 alínea j) do CIVA
  • 25 M32 - IVA - autoliquidação - Artigo 2.º n.º 1 alínea l) do CIVA
  • 31 M34 - IVA - autoliquidação - Artigo 2.º n.º 1 alínea n) do CIVA
  • 26 M40 - IVA - autoliquidação - Artigo 6.º n.º 6 alínea a) do CIVA, a contrário
  • 27 M41 - IVA - autoliquidação - Artigo 8.º n.º 3 do RITI
  • 28 M42 - IVA - autoliquidação - Decreto-Lei n.º 21/2007, de 29 de janeiro
  • 29 M43 - IVA - autoliquidação - Decreto-Lei n.º 362/99, de 16 de setembro
  • 17 M99 - Não sujeito; não tributado (ou similar)

Changelog

2023-06-15
  • Adicionado a gestão de marcações na agenda, através dos endpoints bookings e bookings/unavailables.
  • Adicionado o endpoint para gerar o MBWay numa venda.
2023-02-01
  • Adicionado o parâmetro attachments nos endpoints de envio de email das Vendas (sales/:id/send_email) e Recibos (receipts/:id/send_email), e que permite adicionar 2 anexos adicionais.
2023-01-31
  • Adicionado o tipo de documento Guia de movimentação de activos próprios.
2023-01-21
  • Adicionado o parâmetro language nos clientes, que determina o idioma preferencial.
2022-12-07
  • Adicionado o parâmetro waybill_global nos endpoints das Vendas em que determina se uma guia de transporte ou remessa é de teor global.
2022-12-06
  • Adicionado possibilidade de em séries existentes efectuar a comunicação à AT, para obtenção do ATCUD, para todos os tipos de documento em que a série esteja atribuída.
2022-11-28
  • Removido obrigatoriedade de preenchimento do veículo na criação de guias.
  • Adicionado possibilidade de criar, actualizar e eliminar locais via API.
2022-10-25
  • Adicionado o parâmetro communicate & communicate_documents_types na criação da série para possibilitar a imediata comunicação da série à AT, para obtenção do ATCUD.
  • Adicionado possibilidade de comunicar séries, para obtenção do ATCUD, no processo de criação da série.
  • Criado o endpoint administration/documentstypes/:id/:serie_id/communicate que permite comunicar séries, para obtenção do ATCUD, após ter criado a série.
2022-09-28
  • Permitido preencher o campo country com o código ISO universal relativo ao país.
2022-09-09
  • Adicionado nova mensagem de erro nas Vendas relativo ao país seleccionado.
  • Adicionado nova mensagem de erro nas Vendas relativo ao desconto financeiro aplicado.
2022-06-26
  • Adicionado possibilidade de criar Taxas de IVA com a região de SAF-T de acordo com a norma ISO 3166 de cada país.
2022-05-17
  • Adicionado possibilidade de procurar por artigos através do código de barras.
2022-05-14
  • Criado o endpoint sales/:id/receipt que permite rapidamente criar um Recibo de Cliente baseado numa Factura FT.
2022-04-29
  • Removido o parâmetro avoid_sending_automatic_email dos endpoints das Vendas & Recibos.
  • Removido o parâmetro avoid_sending_automatic_sms dos endpoints das Vendas & Recibos.
  • Corrigido o objectivo do parâmetro force_print nos endpoints das Vendas & Recibos.
  • Adicionado o parâmetro force_email nos endpoints das Vendas & Recibos.
  • Adicionado o parâmetro force_sms nos endpoints das Vendas & Recibos.
  • Adicionado o parâmetro force_sign nos endpoints das Vendas & Recibos.
  • Adicionado o endpoint /sign nas Vendas & Recibos que permite assinar digitalmente documentos.
2022-02-10

Removido a necessidade de introdução do tipo type da série. A criação das séries passa a ser assumido sempre como tipo Normal.

Vendas

Este endpoint visa gerir a emissão de qualquer documento de venda: Facturas, Orçamentos, Encomendas e Guias. Os resultados retornados são os mesmos para qualquer um dos endpoints disponibilizados independentemente do tipo de documento emitido.

A emissão de documentos contabilísticos está dependente do volume de facturação do plano adquirido.

Endpoints
POST /sales/create
POST /sales/:id/update
POST /sales/:id/delete
POST /sales/:id/cancel
POST /sales/:id/duplicate
POST /sales/:id/receipt
POST /sales/:id/credit_note
POST /sales/:id/debit_note
POST /sales/:id/receipt
POST /sales/:id/download
POST /sales/:id/send_email
POST /sales/:id/send_sms
POST /sales/:id/generate_mbref
POST /sales/:id/generate_mbway
POST /sales/:id/sign
POST /sales/summary
POST /sales/find
POST /sales/list

Vendas Criar

sale_reference_id integer

ID da venda a ser referenciada. Apenas deve ser preenchido quando o documento a ser emitido se trata de uma Nota de crédito ou Nota de débito e há uma referência a uma Factura, Factura Simplificada ou Factura Recibo.

issue_date date required

Data de emissão do documento

due_date date

Data de vencimento do documento

document_type mixed required

Tipo de documento. Pode ser enviado o ID ou o descritivo, exemplo: Factura, Factura Recibo, Factura Simplificada, Nota de Crédito, Nota de Débito, Factura Pró-forma, Orçamento, Encomenda, Guia de Transporte, Guia de Remessa, Guia de Consignação, Guia de Devolução, Guia de movimentação de activos próprios.

serie mixed

Série. Pode ser enviado o ID ou o descritivo, exemplo: 2021, 2021A, etc. No caso de não preenchimento será assumido a série pré-definida.

final_discount_financial double

Desconto financeiro €

final_discount_global double

Desconto global %

customer integer required

ID do cliente

vat_number string

Contribuinte do cliente. No caso de não preenchimento será assumido o valor 999999990.

address string required

Morada do cliente

city string required

Localidade do cliente

postal_code string required

Código postal do cliente

country string required

País do cliente

delivery_address_address string

Morada de entrega

delivery_address_city string

Localidade da morada de entrega

delivery_address_postal_code string

Código postal da morada de entrega

delivery_address_country string

País da morada de entrega

payment_method mixed

Forma de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: Numerário, Transferência bancária, etc.

payment_condition mixed

Condição de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: Pronto pagamento, 30 dias, etc.

shipping_mode mixed

Modo de expedição. Pode ser enviado o ID ou o descritivo, exemplo: Correios, Comboio, etc.

shipping_value double

Custo unitário da despesa de transporte

shipping_vat mixed

Taxa de IVA da despesa de transporte. Pode ser enviado o ID, descritivo ou a taxa, exemplo: 23, 13, etc.

price mixed

Tabela de preços utilizada. Pode ser enviado o ID ou o descritivo, exemplo: Preços público, Preços revenda, etc. No caso de não preenchimento será assumido a tabela de preços pré-definida.

currency mixed

Moeda utilizada. Pode ser enviado o ID, símbolo ou descritivo, exemplo: , $, Euro, Dólar. No caso de não preenchimento será assumido a moeda pré-definida.

currency_exchange double

Câmbio da moeda. Caso não seja enviado será assumido 1.

vat_type string required

Tipo de IVA. Deve ser enviado um dos seguintes valores: Debitar IVA, IVA incluído, Não fazer nada.

observations string

Observações do documento

irs_retention_tax double

Taxa de retenção na fonte

vehicle mixed

Veículo utilizado. Este campo apenas deve ser utilizado quando o tipo de documento emitido se trata de uma guia. Pode ser enviado o ID, matrícula ou nome.

employee mixed

Vendedor do documento. Pode ser enviado o ID ou o email.

waybill_shipping_date datetime required if waybill

Data de início de transporte da guia.

waybill_global boolean

Determina se a guia se trata de uma guia global de transporte. Esta opção só pode ser utilizada se o documento a emitir se tratar de uma Guia de Transporte ou Guia de Remessa. Se activo, os campos: customer, vat_number, address, city, postal_code, country, delivery_address_address, delivery_address_city, delivery_address_postal_code, delivery_address_country, discharge_location e location_destiny deixam de ter a obrigatoriedade de preenchimento e serão sempre automaticamente preenchidos pelo Facturalusa com as informações do cliente genérico.

location_origin mixed

Local de origem. Pode ser enviado o ID ou nome do local. No caso de não preenchimento será assumido o local de origem pré-definido.

location_destiny mixed

Local de destino. Pode ser enviado o ID ou nome do local. Não será assumido nenhum valor se não for enviado nada.

cargo_location string

Localidade de carga

discharge_location string

Localidade de descarga

cargo_date datetime

Data de carga

discharge_date datetime

Data de descarga (prevista)

items json array required

Lista de artigos que constam no documento.

id mixed required

ID ou referência do artigo

details string

Descrição adicional a aparecer no documento

price double required

Preço unitário

quantity double required

Quantidade

discount double

Desconto percentual

vat mixed required

Taxa de IVA a aplicar. Pode ser enviado o ID, descritivo ou a taxa, exemplo: 23, 13, etc.

vat_exemption mixed

Isenção de IVA a aplicar. Pode ser enviado o ID ou o código, exemplo: M08, etc. No caso de não preenchimento será assumido o valor M18 - Sem isenção.

language string

Idioma a ser impresso caso o estado do documento seja Terminado. Preencher com PT ou EN. No caso de não preenchimento será assumido o idioma pré-definido.

format string

Formato a ser impresso caso o estado do documento seja Terminado. Preencher com A4 ou POS. No caso de não preenchimento será assumido o valor definido no tipo de documento (que por norma é A4).

paper_size integer

Tamanho / largura do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_left_margin integer

Margem à esquerda do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_right_margin integer

Margem à direita do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_top_margin integer

Margem em cima do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_bottom_margin integer

Margem em baixo do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

force_print boolean

Determina se deve ou não gerar a impressão do documento caso o estado do mesmo seja Terminado. Se preenchido com true o documento será impresso; se preenchido com false o documento não será impresso; se não for preenchido, irá assumir o valor definido no tipo de documento.

force_send_email boolean

Determina se deve ou não enviar via email o documento para o cliente caso o estado do mesmo seja Terminado. Se preenchido com true o documento será enviado; se preenchido com false o documento não será enviado; se não for preenchido, irá assumir o valor definido no tipo de documento.

force_send_sms boolean

Determina se deve ou não enviar SMS para o cliente caso o estado do documento seja Terminado. Se preenchido com true a SMS será enviada; se preenchido com false a SMS não será enviada; se não for preenchido, irá assumir o valor definido no tipo de documento. Esta funcionalidade só funciona se tiver SMS disponíveis.

force_sign boolean

Determina se deve ou não assinar o documento caso o estado do documento seja Terminado e caso o mesmo seja impresso. Se preenchido com true o documento será assinado; se preenchido com false o documento não será assinado; se não for preenchido, irá assumir o valor definido no tipo de documento. Esta funcionalidade só funciona se tiver a Assinatura Digital activada e bem configurada.

status string required

Estado do documento. Deve ser enviado um dos seguintes valores: Rascunho ou Terminado.

Request POST /sales/create
{
    "sale_reference_id": ..,
    "issue_date": ..
    "due_date": ..
    ...
    "items": 
    [
        {
            "id": ..,
            "details": ..
            "price": ..
            "quantity": ..
            "discount": ..
            "vat": ..
            "vat_exemption": ..
        }
    ],
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "number": ..,
        "issue_date": ..,
        "due_date": ..,
        "serie_id": ..,
        "document_type_id": ..,
        "gross_total": ..,
        "total_discount": ..,
        "net_total": ..,
        "total_base_vat": ..,
        "total_vat": ..,
        "total_shipping": ..,
        "total_services": ..,
        "grand_total": ..,
        "final_discount_financial": ..,
        "final_discount_global": ..,
        "final_discount_value": ..,
        "customer_id": ..,
        "customer_code": ..,
        "customer_name": ..,
        "customer_vat_number": ..,
        "customer_country": ..,
        "customer_city": ..,
        "customer_address": ..,
        "customer_postal_code": ..,
        "customer_delivery_address_country": ..,
        "customer_delivery_address_address": ..,
        "customer_delivery_address_city": ..,
        "customer_delivery_address_postal_code": ..,
        "company_name": ..,
        "company_vat_number": ..,
        "company_country": ..,
        "company_address": ..,
        "company_city": ..,
        "company_postal_code": ..,
        "company_vat_scheme": ..,
        "payment_method_id": ..,
        "payment_condition_id": ..,
        "shipping_mode_id": ..,
        "shipping_value": ..,
        "shipping_vat_id": ..,
        "price_id": ..,
        "currency_id": ..,
        "currency_exchange": ..,
        "vehicle_id": ..,
        "employee_id": ..,
        "waybill_shipping_date": ..,
        "waybill_global": ..,
        "location_origin_id": ..,
        "location_origin_name": ..,
        "location_origin_country": ..,
        "location_origin_address": ..,
        "location_origin_city": ..,
        "location_origin_postal_code": ..,
        "warehouse_origin_id": ..,
        "warehouse_destiny_id": ..,
        "location_destiny_id": ..,
        "cargo_location": ..,
        "discharge_location": ..,
        "cargo_date": ..,
        "discharge_date": ..,
        "mb_entity": ..,
        "mb_sub_entity": ..,
        "mb_reference": ..,
        "at_code": ..,
        "at_message": ..,
        "vat_type": ..,
        "observations": ..,
        "irs_retention_apply": ..,
        "irs_retention_base": ..,
        "irs_retention_total": ..,
        "irs_retention_tax": ..,
        "url_file": ..,
        "file_previewed": ..,
        "file_last_generated": ..,
        "status": ..,
        "status_last_change": ..,
        "created_by": ..,
        "finished_by": ..,
        "canceled_by": ..,
        "canceled_at": ..,
        "canceled_reason": ..,
        "updated_at": ..,
        "created_at": ..,
        "reference": [],
        "serie": [],
        "documenttype": [],
        "documenttypeserie": [],
        "paymentmethod": [],
        "paymentcondition": [],
        "shippingmode": [],
        "shippingvat": [],
        "price": [],
        "currency": [],
        "vehicle": [],
        "employee": [],
        "locationdestiny": [],
        "warehouseorigin": [],
        "warehousedestiny": [],
        "vats": [],
        "items": [],
        "createdby": [],
        "finishedby": [],
        "canceledby": [],
        "customercountry": [],
        "accountopen": [],
    }
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • Não tem permissões para executar esta operação
  • Na versão demo o total não pode ultrapassar os 10.000,00€
  • Não preencheu todos os campos obrigatórios
  • O tipo de documento não existe ou não se encontra activo
  • Não preencheu a série ou não existe nenhuma série pré-definida para utilizar
  • Não preencheu a moeda ou não existe nenhuma moeda pré-definida para utilizar
  • Seleccione pelo menos um artigo
  • Os documentos tem o limite máximo de 100 artigos
  • O cliente não existe
  • O cliente não se encontra activo
  • O estado do documento não é válido
  • A série não se encontra atribuída no tipo de documento seleccionado
  • A série não se encontra activa no tipo de documento seleccionado
  • A série encontra-se expirada
  • A série não se encontra comunicada à AT no tipo de documento seleccionado. A partir de 2023 passou a ser um requisito obrigatório
  • O local não existe ou não se encontra activo
  • Não preencheu correctamente o desconto financeiro (formato aceite: 0,00 ou 0.00)
  • Não preencheu correctamente o desconto global (formato aceite: 0,00 ou 0.00)
  • Um ou mais artigos mal preenchidos, na linha: X
  • O artigo não existe
  • Não preencheu todos os campos obrigatórios nos artigos
  • Não preencheu correctamente o preço unitário (formato aceite: 0,00000 ou 0.00000)
  • Não preencheu correctamente a quantidade (formato aceite: 0,00000 ou 0.00000)
  • Não preencheu correctamente o desconto (formato aceite: 0,00 ou 0.00)
  • Quando existe isenção de IVA é obrigatório que a taxa de IVA seja zero
  • Quando o tipo de IVA seleccionado é «Não fazer nada» todos os artigos do documento devem ter a Taxa de IVA 0% e o respectivo motivo de isenção de IVA aplicado
  • A data início transporte não contêm um formato válido (ano-mês-dia horas:minutos)
  • É obrigatório preencher o campo da data de início de transporte nas Guias
  • A data e hora da guia não pode ser inferior à data e hora actual
  • O código postal é de preenchimento obrigatório em Portugal
  • O local de destino é de preenchimento obrigatório
  • O total não pode ser negativo ou igual a zero
  • Já atingiu o volume máximo de facturação ou a soma do total geral do documento actual com o valor actual da subscrição ultrapassa o limite
  • Não pode criar este documento sobre o contribuinte de consumidor final
  • Artigo 36.º alinea 15 do CIVA : É necessária a identificação e domicílio do cliente quando o valor total da factura for igual ou superior a 1000,00€
  • Na Factura Simplificada o total base não pode ser superior a 1000.00€ para particulares
  • Na Factura Simplificada o total de serviços não pode exceder 100,00€ para particulares
  • Na Factura Simplificada o total base não pode ser superior a 100.00€ para empresas
  • Formato/valor de câmbio inválido
  • Não preencheu correctamente a taxa de retenção de IRS (formato aceite: 0,00 ou 0.00)
  • Não preencheu correctamente as despesas de transporte
  • Não preencheu correctamente o valor da despesa de transporte (formato aceite: 0,00 ou 0.00)
  • A data emissão não contêm um formato válido (ano-mês-dia)
  • A data de vencimento não contêm um formato válido (ano-mês-dia)
  • A data de vencimento não pode ser inferior à data de emissão
  • A data de carga não contêm um formato válido (ano-mês-dia horas:minutos)
  • A data e hora da carga não pode ser inferior à data e hora actual
  • A data de descarga não contêm um formato válido (ano-mês-dia horas:minutos)
  • A data e hora da descarga não pode ser inferior à data e hora actual
  • O local de origem e o local de destino não podem ser iguais!
  • Despacho n.º 8632/2014: Quando acontecer uma situação de erro ou anomalia (...) devem ser encerradas as séries em utilização. A série encontra-se bloqueada
  • Já existe um documento do mesmo tipo e da mesma série emitido com uma data superior à data de emissão escolhida
  • O documento referenciado não existe
  • Só pode referenciar Facturas, Facturas Recibo ou Facturas Simplificadas
  • O cliente do documento rectificativo não pode ser diferente do documento original
  • A data de emissão do documento rectificativo não pode ser inferior à do documento original
  • Um ou mais artigos não se encontram atribuídos ao documento que está a ser rectificado
  • Um ou mais artigos nunca foram facturados a este cliente e está a lançar um documento rectificativo
  • O total geral do documento rectificativo não pode ser superior ao total geral do documento original
  • Os valores (quantidades, preços, descontos, taxas iva, totais) dos artigos do documento rectificativo tem de ser iguais ou inferiores aos valores do documento original
  • O desconto financeiro não pode ser superior à soma dos preços unitários dos artigos
  • As guias globais só podem ser criadas nos tipos de documento Guia de Transporte e Guia de Remessa
  • O país introduzido é inválido

Vendas Actualizar

Apenas pode ser utilizado caso o documento se encontre em rascunho.

sale_reference_id integer

ID da venda a ser referenciada. Apenas deve ser preenchido quando o documento a ser emitido se trata de uma Nota de crédito ou Nota de débito e há uma referência a uma Factura, Factura Simplificada ou Factura Recibo.

issue_date date required

Data de emissão do documento

due_date date

Data de vencimento do documento

document_type mixed required

Tipo de documento. Pode ser enviado o ID ou o descritivo, exemplo: Factura, Factura Recibo, Factura Simplificada, Nota de Crédito, Nota de Débito, Factura Pró-forma, Orçamento, Encomenda, Guia de Transporte, Guia de Remessa, Guia de Consignação, Guia de Devolução, Guia de movimentação de activos próprios.

serie mixed

Série. Pode ser enviado o ID ou o descritivo, exemplo: 2021, 2021A, etc. No caso de não preenchimento será assumido a série pré-definida.

final_discount_financial double

Desconto financeiro €

final_discount_global double

Desconto global %

customer integer required

ID do cliente

vat_number string

Contribuinte do cliente. No caso de não preenchimento será assumido o valor 999999990.

address string required

Morada do cliente

city string required

Localidade do cliente

postal_code string required

Código postal do cliente

country string required

País do cliente

delivery_address_address string

Morada de entrega

delivery_address_city string

Localidade da morada de entrega

delivery_address_postal_code string

Código postal da morada de entrega

delivery_address_country string

País da morada de entrega

payment_method mixed

Forma de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: Numerário, Transferência bancária, etc.

payment_condition mixed

Condição de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: Pronto pagamento, 30 dias, etc.

shipping_mode mixed

Modo de expedição. Pode ser enviado o ID ou o descritivo, exemplo: Correios, Comboio, etc.

shipping_value double

Custo unitário da despesa de transporte

shipping_vat mixed

Taxa de IVA da despesa de transporte. Pode ser enviado o ID, descritivo ou a taxa, exemplo: 23, 13, etc.

price mixed

Tabela de preços utilizada. Pode ser enviado o ID ou o descritivo, exemplo: Preços público, Preços revenda, etc.

currency mixed

Moeda utilizada. Pode ser enviado o ID, símbolo ou descritivo, exemplo: , $, Euro, Dólar. No caso de não preenchimento será assumido a moeda pré-definida.

currency_exchange double

Câmbio da moeda. Caso não seja enviado será assumido 1.

vat_type string required

Tipo de IVA. Deve ser enviado um dos seguintes valores: Debitar IVA, IVA incluído, Não fazer nada.

observations string

Observações do documento

irs_retention_tax double

Taxa de retenção na fonte

vehicle mixed

Veículo utilizado. Este campo apenas deve ser utilizado quando o tipo de documento emitido se trata de uma guia. Pode ser enviado o ID, matrícula ou nome.

employee mixed

Vendedor do documento. Pode ser enviado o ID ou o email.

waybill_shipping_date datetime required if waybill

Data de início de transporte da guia.

waybill_global boolean

Determina se a guia se trata de uma guia global de transporte. Esta opção só pode ser utilizada se o documento a emitir se tratar de uma Guia de Transporte ou Guia de Remessa. Se activo, os campos: customer, vat_number, address, city, postal_code, country, delivery_address_address, delivery_address_city, delivery_address_postal_code, delivery_address_country, discharge_location e location_destiny deixam de ter a obrigatoriedade de preenchimento e serão sempre automaticamente preenchidos pelo Facturalusa com as informações do cliente genérico.

location_origin mixed

Local de origem. Pode ser enviado o ID ou nome do local. No caso de não preenchimento será assumido o local de origem pré-definido.

location_destiny mixed

Local de destino. Pode ser enviado o ID ou nome do local. Não será assumido nenhum valor se não for enviado nada.

cargo_location string

Localidade de carga

discharge_location string

Localidade de descarga

cargo_date datetime

Data de carga

discharge_date datetime

Data de descarga (prevista)

items json array required

Lista de artigos que constam no documento.

id mixed required

ID ou referência do artigo

details string

Descrição adicional a aparecer no documento

price double required

Preço unitário

quantity double required

Quantidade

discount double

Desconto percentual

vat mixed required

Taxa de IVA a aplicar. Pode ser enviado o ID, descritivo ou a taxa, exemplo: 23, 13, etc.

vat_exemption mixed

Isenção de IVA a aplicar. Pode ser enviado o ID ou o código, exemplo: M08, etc. No caso de não preenchimento será assumido o valor M18 - Sem isenção.

language string

Idioma a ser impresso caso o estado do documento seja Terminado. Preencher com PT ou EN. No caso de não preenchimento será assumido o idioma pré-definido.

format string

Formato a ser impresso caso o estado do documento seja Terminado. Preencher com A4 ou POS. No caso de não preenchimento será assumido o valor definido no tipo de documento (que por norma é A4).

paper_size integer

Tamanho / largura do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_left_margin integer

Margem à esquerda do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_right_margin integer

Margem à direita do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_top_margin integer

Margem em cima do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_bottom_margin integer

Margem em baixo do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

force_print boolean

Determina se deve ou não gerar a impressão do documento caso o estado do mesmo seja Terminado. Se preenchido com true o documento será impresso; Se preenchido com false o documento não será impresso; se não for preenchido, irá assumir o valor definido no tipo de documento.

force_send_email boolean

Determina se deve ou não enviar via email o documento para o cliente caso o estado do mesmo seja Terminado. Se preenchido com true o documento será enviado; Se preenchido com false o documento não será enviado; se não for preenchido, irá assumir o valor definido no tipo de documento.

force_send_sms boolean

Determina se deve ou não enviar SMS para o cliente caso o estado do documento seja Terminado. Se preenchido com true a SMS será enviada; Se preenchido com false a SMS não será enviada; se não for preenchido, irá assumir o valor definido no tipo de documento. Esta funcionalidade só funciona se tiver SMS disponíveis.

force_sign boolean

Determina se deve ou não assinar o documento caso o estado do documento seja Terminado e caso o mesmo seja impresso. Se preenchido com true o documento será assinado; se preenchido com false o documento não será assinado; se não for preenchido, irá assumir o valor definido no tipo de documento. Esta funcionalidade só funciona se tiver a Assinatura Digital activada e bem configurada.

status string required

Estado do documento. Deve ser enviado um dos seguintes valores: Rascunho ou Terminado.

Request POST /sales/:id/update
{
    "sale_reference_id": ..,
    "issue_date": ..
    "due_date": ..
    ...
    "items": 
    [
        {
            "id": ..,
            "details": ..
            "price": ..
            "quantity": ..
            "discount": ..
            "vat": ..
            "vat_exemption": ..
        }
    ],
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "number": ..,
        "issue_date": ..,
        "due_date": ..,
        "serie_id": ..,
        "document_type_id": ..,
        "gross_total": ..,
        "total_discount": ..,
        "net_total": ..,
        "total_base_vat": ..,
        "total_vat": ..,
        "total_shipping": ..,
        "total_services": ..,
        "grand_total": ..,
        "final_discount_financial": ..,
        "final_discount_global": ..,
        "final_discount_value": ..,
        "customer_id": ..,
        "customer_code": ..,
        "customer_name": ..,
        "customer_vat_number": ..,
        "customer_country": ..,
        "customer_city": ..,
        "customer_address": ..,
        "customer_postal_code": ..,
        "customer_delivery_address_country": ..,
        "customer_delivery_address_address": ..,
        "customer_delivery_address_city": ..,
        "customer_delivery_address_postal_code": ..,
        "company_name": ..,
        "company_vat_number": ..,
        "company_country": ..,
        "company_address": ..,
        "company_city": ..,
        "company_postal_code": ..,
        "company_vat_scheme": ..,
        "payment_method_id": ..,
        "payment_condition_id": ..,
        "shipping_mode_id": ..,
        "shipping_value": ..,
        "shipping_vat_id": ..,
        "price_id": ..,
        "currency_id": ..,
        "currency_exchange": ..,
        "vehicle_id": ..,
        "employee_id": ..,
        "waybill_shipping_date": ..,
        "waybill_global": ..,
        "location_origin_id": ..,
        "location_origin_name": ..,
        "location_origin_country": ..,
        "location_origin_address": ..,
        "location_origin_city": ..,
        "location_origin_postal_code": ..,
        "warehouse_origin_id": ..,
        "warehouse_destiny_id": ..,
        "location_destiny_id": ..,
        "cargo_location": ..,
        "discharge_location": ..,
        "cargo_date": ..,
        "discharge_date": ..,
        "mb_entity": ..,
        "mb_sub_entity": ..,
        "mb_reference": ..,
        "at_code": ..,
        "at_message": ..,
        "vat_type": ..,
        "observations": ..,
        "irs_retention_apply": ..,
        "irs_retention_base": ..,
        "irs_retention_total": ..,
        "irs_retention_tax": ..,
        "url_file": ..,
        "file_previewed": ..,
        "file_last_generated": ..,
        "status": ..,
        "status_last_change": ..,
        "created_by": ..,
        "finished_by": ..,
        "canceled_by": ..,
        "canceled_at": ..,
        "canceled_reason": ..,
        "updated_at": ..,
        "created_at": ..,
        "reference": [],
        "serie": [],
        "documenttype": [],
        "documenttypeserie": [],
        "paymentmethod": [],
        "paymentcondition": [],
        "shippingmode": [],
        "shippingvat": [],
        "price": [],
        "currency": [],
        "vehicle": [],
        "employee": [],
        "locationdestiny": [],
        "warehouseorigin": [],
        "warehousedestiny": [],
        "vats": [],
        "items": [],
        "createdby": [],
        "finishedby": [],
        "canceledby": [],
        "customercountry": [],
        "accountopen": [],
    }
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Na versão demo o total não pode ultrapassar os 10.000,00€
  • Não preencheu todos os campos obrigatórios
  • O tipo de documento não existe ou não se encontra activo
  • Não preencheu a série ou não existe nenhuma série pré-definida para utilizar
  • Não preencheu a moeda ou não existe nenhuma moeda pré-definida para utilizar
  • Seleccione pelo menos um artigo
  • Os documentos tem o limite máximo de 100 artigos
  • O cliente não existe
  • O cliente não se encontra activo
  • O estado do documento não é válido
  • A série não se encontra atribuída no tipo de documento seleccionado
  • A série não se encontra activa no tipo de documento seleccionado
  • A série encontra-se expirada
  • A série não se encontra comunicada à AT no tipo de documento seleccionado. A partir de 2023 passou a ser um requisito obrigatório
  • O local não existe ou não se encontra activo
  • Não preencheu correctamente o desconto financeiro (formato aceite: 0,00 ou 0.00)
  • Não preencheu correctamente o desconto global (formato aceite: 0,00 ou 0.00)
  • Um ou mais artigos mal preenchidos, na linha: X
  • O artigo não existe
  • Não preencheu todos os campos obrigatórios nos artigos
  • Não preencheu correctamente o preço unitário (formato aceite: 0,00000 ou 0.00000)
  • Não preencheu correctamente a quantidade (formato aceite: 0,00000 ou 0.00000)
  • Não preencheu correctamente o desconto (formato aceite: 0,00 ou 0.00)
  • Quando existe isenção de IVA é obrigatório que a taxa de IVA seja zero
  • Quando o tipo de IVA seleccionado é «Não fazer nada» todos os artigos do documento devem ter a Taxa de IVA 0% e o respectivo motivo de isenção de IVA aplicado
  • A data início transporte não contêm um formato válido (ano-mês-dia horas:minutos)
  • É obrigatório preencher o campo da data de início de transporte nas Guias
  • A data e hora da guia não pode ser inferior à data e hora actual
  • O código postal é de preenchimento obrigatório em Portugal
  • O local de destino é de preenchimento obrigatório
  • O total não pode ser negativo ou igual a zero
  • Já atingiu o volume máximo de facturação ou a soma do total geral do documento actual com o valor actual da subscrição ultrapassa o limite
  • Não pode criar este documento sobre o contribuinte de consumidor final
  • Artigo 36.º alinea 15 do CIVA : É necessária a identificação e domicílio do cliente quando o valor total da factura for igual ou superior a 1000,00€
  • Na Factura Simplificada o total base não pode ser superior a 1000.00€ para particulares
  • Na Factura Simplificada o total de serviços não pode exceder 100,00€ para particulares
  • Na Factura Simplificada o total base não pode ser superior a 100.00€ para empresas
  • Formato/valor de câmbio inválido
  • Não preencheu correctamente a taxa de retenção de IRS (formato aceite: 0,00 ou 0.00)
  • Não preencheu correctamente as despesas de transporte
  • Não preencheu correctamente o valor da despesa de transporte (formato aceite: 0,00 ou 0.00)
  • A data emissão não contêm um formato válido (ano-mês-dia)
  • A data de vencimento não contêm um formato válido (ano-mês-dia)
  • A data de vencimento não pode ser inferior à data de emissão
  • A data de carga não contêm um formato válido (ano-mês-dia horas:minutos)
  • A data e hora da carga não pode ser inferior à data e hora actual
  • A data de descarga não contêm um formato válido (ano-mês-dia horas:minutos)
  • A data e hora da descarga não pode ser inferior à data e hora actual
  • O local de origem e o local de destino não podem ser iguais!
  • Despacho n.º 8632/2014: Quando acontecer uma situação de erro ou anomalia (...) devem ser encerradas as séries em utilização. A série encontra-se bloqueada
  • Já existe um documento do mesmo tipo e da mesma série emitido com uma data superior à data de emissão escolhida
  • O documento referenciado não existe
  • Só pode referenciar Facturas, Facturas Recibo ou Facturas Simplificadas
  • O cliente do documento rectificativo não pode ser diferente do documento original
  • A data de emissão do documento rectificativo não pode ser inferior à do documento original
  • Um ou mais artigos não se encontram atribuídos ao documento que está a ser rectificado
  • Um ou mais artigos nunca foram facturados a este cliente e está a lançar um documento rectificativo
  • O total geral do documento rectificativo não pode ser superior ao total geral do documento original
  • Os valores (quantidades, preços, descontos, taxas iva, totais) dos artigos do documento rectificativo tem de ser iguais ou inferiores aos valores do documento original
  • O desconto financeiro não pode ser superior à soma dos preços unitários dos artigos
  • As guias globais só podem ser criadas nos tipos de documento Guia de Transporte e Guia de Remessa
  • O país introduzido é inválido

Vendas Eliminar

Apenas pode ser utilizado caso o documento se encontre em rascunho.

Request POST /sales/:id/delete
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação

Vendas Cancelar

Apenas pode ser utilizado caso o documento se encontre terminado e ainda não tenha sido cancelado.

reason string required if invoice or waybill minimum 15 chars

Justificação da anulação do documento. Obrigatório preencher no caso de documentos de Facturação (FT, FR, FS, NC, ND) e Guias.

Request POST /sales/:id/cancel
{
    "reason": ..,
}
Response 200
{
    "status": true,
    "url_file": ...
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • É obrigatório o preenchimento da razão em documentos do tipo Facturação e Guias
  • A anulação só é possível caso a data e hora actual não seja superior à data e hora da guia
  • A anulação só é possível caso a data e hora actual não seja superior à data e hora da guia
  • Despacho n.º 8632/2014: Não é permitido a A anulação de documentos sobre os quais já tenha sido emitido documento retificativo (nota de crédito ou débito) ainda que parcial, sem a prévia anulação do respetivo documento retificativo
  • Não é permitido a anulação de documentos de Facturação onde a data de emissão é diferente da data actual
  • O documento já se encontra atribuído no Recibo X. Por favor anule primeiro este documento.

Vendas Duplicar

Apenas pode ser utilizado caso o documento se encontre terminado.

document_type string required

Tipo de documento. Pode ser enviado o ID ou o descritivo, exemplo: Factura, Factura Recibo, Factura Simplificada, Nota de Crédito, Nota de Débito, Factura Pró-forma, Orçamento, Encomenda, Guia de Transporte, Guia de Remessa, Guia de Consignação, Guia de Devolução, Guia de movimentação de activos próprios.

Request POST /sales/:id/duplicate
{
    "document_type": ..,
}
Response 200
{
    "status": true,
    "id": ...
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • O tipo de documento seleccionado não se encontra activo

Vendas Recibo

Permite criar um Recibo de Cliente a partir da uma Factura FT, o documento é sempre criado no estado de Rascunho. Apenas pode ser utilizado caso o documento se encontre terminado e ainda não tenha sido cancelado.

Request POST /sales/:id/receipt
Sem parâmetros
Response 200
{
    "status": true,
    "id": ...
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • O tipo de documento Recibo de Cliente não existe ou não se encontra activo
  • Não é possível criar um recibo sobre o documento estipulado
  • O documento não possui valores em aberto

Vendas Nota de crédito

Apenas pode ser utilizado caso o documento se encontre terminado e ainda não tenha sido cancelado.

Request POST /sales/:id/credit_note
Sem parâmetros
Response 200
{
    "status": true,
    "id": ...
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • O tipo de documento seleccionado não se encontra activo
  • Não é possível criar uma nota de crédito sobre o documento estipulado

Vendas Nota de débito

Apenas pode ser utilizado caso o documento se encontre terminado e ainda não tenha sido cancelado.

Request POST /sales/:id/debit_note
Sem parâmetros
Response 200
{
    "status": true,
    "id": ...
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • O tipo de documento seleccionado não se encontra activo
  • Não é possível criar uma nota de crédito sobre o documento estipulado

Vendas Download

Apenas pode ser utilizado caso o documento se encontre terminado.

language string

Idioma a ser impresso. Preencher com PT ou EN. No caso de não preenchimento será assumido o idioma previamente guardado.

format string

Formato a ser impresso. Preencher com A4 ou POS. No caso de não preenchimento será assumido o formato previamente guardado.

paper_size integer

Tamanho / largura do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_left_margin integer

Margem à esquerda do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_right_margin integer

Margem à direita do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_top_margin integer

Margem em cima do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_bottom_margin integer

Margem em baixo do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

issue string

Via a imprimir. Preencher com 2ª via ou Original. No caso de não preenchimento será assumido 2ª via.

max_items_per_page integer max 25

Nº de artigos a imprimir por página. No caso de não preenchimento será assumido o valor pré-definido.

Request POST /sales/:id/download
{
    "language": ..,
    "format": ..,
    "issue": ..,
    "max_items_per_page": ..
}
Response 200
{
    "status": true,
    "url_file": ...
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação

Vendas Enviar email

Apenas pode ser utilizado caso o documento se encontre terminado.

subject string

Assunto do email. No caso de não preenchimento será assumido o assunto no template.

message string

Corpo do email. No caso de não preenchimento será assumido o corpo do email no template.

to json required

Para quem vai enviar o email

name string required

Nome

email string required

Email

cc string

Cópia do email em CC para N emails. Valores separados por vírgula.

attachments json array

Permite adicionar 2 anexos adicionais. As extensões dos ficheiros autorizadas são: png, jpg, jpeg, bmp, pdf, doc, docx, xls, xlsx, zip, 7z, rar, csv, txt, xml,

filename string required

Nome do ficheiro

url string required

URL do ficheiro

Request POST /sales/:id/send_email
{
    "subject": ..,
    "message": ..,
    "to": { "name": .., "email": .. },
    "cc": email1,email2,
    "attachments": [{ "filename": .., "url": ..}]
}
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Não preencheu todos os campos obrigatórios
  • Um ou mais emails são inválidos
  • Só é permitido no máximo 2 anexos
  • O anexo adicionado aparenta ser inválido
  • A extensão do anexo adicionado é inválida
  • O URL do anexo adicionado é inválido
  • Não foi possível enviar o email, por favor tente mais tarde. Se o problema persistir, entre em contacto com o suporte

Vendas Enviar sms

Apenas pode ser utilizado caso o documento se encontre terminado.

to json array required

Um ou mais nº de telemóvel

name string required

Nome

mobile string required

Nº de telemóvel. Sem espaços, sem +351, nº nacional.

message string

Mensagem a enviar. No caso de não preenchimento será assumido a mensagem no template.

Request POST /sales/:id/send_sms
{
    "to": 
    [
        {
            "name": ..,
            "mobile": ..
        }
    ],
    "message": ..
}
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Não preencheu todos os campos obrigatórios
  • Obrigatório o preenchimento do nome
  • Obrigatório o preenchimento do telemóvel
  • O telemóvel é inválido
  • Precisa de configurar primeiro o nome do remetente e o documento de identificação
  • Ainda não foi aprovado o envio de SMS a partir do remetente configurado. Por favor aguarde por um email nosso ou consulte diariamente as configurações para saber o estado em que se encontra o pedido.
  • Não possui SMS disponíveis suficientes

Vendas Gerar ref. multibanco

Apenas pode ser utilizado caso o documento se encontre no estado Terminado, ainda não tenha sido cancelado e nos seguintes tipos de documento: Factura, Factura Pró-forma, Encomenda e Orçamento.

Request POST /sales/:id/generate_mbref
Sem parâmetros
Response 200
{
    "status": true,
    "data": 
    {
        "entity" => .., 
        "sub_entity" => .., 
        "reference" => ..
    }
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Não é possível gerar a referência MB no tipo de documento seleccionado
  • O documento já possui uma referência de multibanco
  • Não existe nenhuma configuração de referências de multibanco

Vendas Gerar MBWay

Apenas pode ser utilizado caso o documento se encontre no estado Terminado, ainda não tenha sido cancelado e nos seguintes tipos de documento: Factura, Factura Pró-forma, Encomenda e Orçamento.

Request POST /sales/:id/generate_mbway
Sem parâmetros
Response 200
{
    "status": true,
    "mbway_link": ..
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Não é possível gerar o MBWay no tipo de documento seleccionado
  • Não existe nenhuma configuração de MBWay

Vendas Assinar digitalmente

Apenas pode ser utilizado caso o documento se encontre terminado.

Request POST /sales/:id/sign
Sem parâmetros
Response 200
{
    "status": true,
    "url_file": ..
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • O documento já se encontra digitalmente assinado
  • Não existe nenhuma configuração de assinatura digital ou a mesma encontra-se com erros
  • Não foi possível assinar o documento. Consulte a página da assinatura digital para visualizar o erro

Vendas Sumário

Permite calcular em tempo real os totais (total de iva, total geral, etc) que vão ser emitidos no documento.

document_type mixed required

Tipo de documento. Pode ser enviado o ID ou o descritivo, exemplo: Factura, Factura Recibo, Factura Simplificada, Nota de Crédito, Nota de Débito, Factura Pró-forma, Orçamento, Encomenda, Guia de Transporte, Guia de Remessa, Guia de Consignação, Guia de Devolução, Guia de movimentação de activos próprios.

final_discount_financial double

Desconto financeiro €

final_discount_global double

Desconto global %

shipping_mode mixed

Modo de expedição. Pode ser enviado o ID ou o descritivo, exemplo: Correios, Comboio, etc.

shipping_value double

Custo unitário da despesa de transporte

shipping_vat mixed

Taxa de IVA da despesa de transporte. Pode ser enviado o ID, descritivo ou a taxa, exemplo: 23, 13, etc.

currency mixed

Moeda utilizada. Pode ser enviado o ID, símbolo ou descritivo, exemplo: , $, Euro, Dólar. No caso de não preenchimento será assumido a moeda pré-definida.

currency_exchange double

Câmbio da moeda. Caso não seja enviado será assumido 1.

vat_type string required

Tipo de IVA. Deve ser enviado um dos seguintes valores: Debitar IVA, IVA incluído, Não fazer nada.

irs_retention_tax double

Taxa de retenção na fonte

items json array required

Lista de artigos que constam no documento.

id mixed required

ID ou referência do artigo

details string

Descrição adicional a aparecer no documento

price double required

Preço unitário

quantity double required

Quantidade

discount double

Desconto percentual

vat mixed required

Taxa de IVA a aplicar. Pode ser enviado o ID, descritivo ou a taxa, exemplo: 23, 13, etc.

vat_exemption mixed

Isenção de IVA a aplicar. Pode ser enviado o ID ou o código, exemplo: M08, etc. No caso de não preenchimento será assumido o valor M18 - Sem isenção.

Request POST /sales/summary
{
    "document_type": ..,
    "final_discount_financial": ..,
    "final_discount_global": ..,
    "shipping_mode": ..,
    "shipping_value": ..,
    "shipping_vat": ..,
    "currency": ..,
    "currency_exchange": ..,
    "vat_type": ..,
    "irs_retention_tax": ..,
    "items": 
    [
        {
            "id": ..,
            "details": ..
            "price": ..
            "quantity": ..
            "discount": ..
            "vat": ..
            "vat_exemption": ..
        }
    ],
}
Response 200
{
    "status":true,
    "data":
    {
        "gross_total": ..,
        "total_discount": ..,
        "net_total": ..,
        "total_base_vat": ..,
        "total_vat": ..,
        "total_shipping": ..,
        "grand_total": ..,
        "grand_total_with_currency_exchange": ..,
        "final_discount_financial": ..,
        "final_discount_global": ..,
        "final_discount_global_value": ..,
        "total_services": ..,
        "total_quantity": ..,
        "irs_retention_apply": ..,
        "irs_retention_base": ..,
        "irs_retention_total": ..,
        "irs_retention_tax": ..,
        "items":
        [
            {
                "sale_id": ..,
                "item_id": ..,
                "item_details": ..,
                "price": ..,
                "quantity": ..,
                "discount": ..,
                "gross_total": ..,
                "net_total": ..,
                "total_base_vat": ..,
                "total_vat": ..,
                "total_discount": ..,
                "grand_total": ..,
                "vat_id": ..,
                "unit_id": ..,
                "vat_exemption_id": ..,
            }
        ],
        "vats":
        [
            {
                "sale_id": ..,
                "vat_id": ..,
                "vat_tax": ..,
                "total_base_vat": ..,
                "total_vat": ..,
            }
        ]
    }
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Vendas Procurar

Permite procurar por uma venda.

value mixed required

Valor a procurar

search_in string required

Determina em que campo deve ser procurado. Deve ser enviado um dos seguintes valores: ID, Document Number. No caso da procura ser efectuada no nº do documento, a seguinte nomenclatura exemplo deve ser enviada: FT A/4921.

Request POST /sales/find
{
    "value": ..,
    "search_in": ..
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "number": ..,
        "issue_date": ..,
        "due_date": ..,
        ...
    }
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • O valor do campo value é obrigatório
  • O valor do campo search_in é inválido
  • Não tem permissões para executar esta operação

Vendas Lista

Devolve a lista de vendas. Devolve no máximo 15 resultados.

value mixed

Valor a procurar

search_in string

Determina em que campo deve ser procurado. Pode ser enviado um dos seguintes valores: ID, Document Number, Customer, Vat Number. No caso da procura ser efectuada no nº do documento, a seguinte nomenclatura exemplo deve ser enviada: FT A/4921.

type string

Determina que tipos de documentos devolve. Pode ser enviado um dos seguintes valores: Facturação, Orçamentos, Encomendas, Guias.

skip integer

Determina que indice deve saltar. Deve ser enviado um valor multiplicador de 15.

Request POST /sales/list
{
    "value": ..,
    "search_in": ..,
    "type": ..,
    "skip": ..,
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "number": ..,
            "issue_date": ..,
            "due_date": ..,
            ...
        }
    ]
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • Não tem permissões para executar esta operação

Recibos

Este endpoint visa gerir a emissão de recibos.

Endpoints
POST /receipts/create
POST /receipts/:id/update
POST /receipts/:id/delete
POST /receipts/:id/cancel
POST /receipts/:id/download
POST /receipts/:id/send_email
POST /receipts/:id/send_sms
POST /receipts/:id/sign
POST /receipts/summary
POST /receipts/find
POST /receipts/list

Recibos Criar

issue_date date required

Data de emissão do documento

receipt_date date required

Data de recebimento do documento

document_type mixed required

Tipo de documento. Pode ser enviado o ID ou o descritivo, exemplo: Recibo de Cliente.

serie mixed

Série. Pode ser enviado o ID ou o descritivo, exemplo: 2021, 2021A, etc. No caso de não preenchimento será assumido a série pré-definida.

customer integer required

ID do cliente

vat_number string

Contribuinte do cliente. No caso de não preenchimento será assumido o valor 999999990.

address string required

Morada do cliente

city string required

Localidade do cliente

postal_code string required

Código postal do cliente

country string required

País do cliente

payment_method mixed

Forma de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: Numerário, Transferência bancária, etc.

currency mixed

Moeda utilizada. Pode ser enviado o ID, símbolo ou descritivo, exemplo: , $, Euro, Dólar. No caso de não preenchimento será assumido a moeda pré-definida.

currency_exchange double

Câmbio da moeda. Caso não seja enviado será assumido 1.

observations string

Observações do documento

location_origin mixed

Local de origem. Pode ser enviado o ID ou nome do local. No caso de não preenchimento será assumido o local de origem pré-definido.

sales json array required

Lista de vendas que constam no documento.

id integer required

ID da venda

percentage_discount double

Desconto percentual

unit_discount double

Desconto unitário

total_paid double required

Valor pago

language string

Idioma a ser impresso caso o estado do documento seja Terminado. Preencher com PT ou EN. No caso de não preenchimento será assumido o idioma pré-definido.

format string

Formato a ser impresso caso o estado do documento seja Terminado. Preencher com A4 ou POS. No caso de não preenchimento será assumido o valor definido no tipo de documento (que por norma é A4).

paper_size integer

Tamanho / largura do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_left_margin integer

Margem à esquerda do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_right_margin integer

Margem à direita do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_top_margin integer

Margem em cima do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_bottom_margin integer

Margem em baixo do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

force_print boolean

Determina se deve ou não gerar a impressão do documento caso o estado do mesmo seja Terminado. Se preenchido com true o documento será impresso; se preenchido com false o documento não será impresso; se não for preenchido, irá assumir o valor definido no tipo de documento.

force_send_email boolean

Determina se deve ou não enviar via email o documento para o cliente caso o estado do mesmo seja Terminado. Se preenchido com true o documento será enviado; se preenchido com false o documento não será enviado; se não for preenchido, irá assumir o valor definido no tipo de documento.

force_send_sms boolean

Determina se deve ou não enviar SMS para o cliente caso o estado do documento seja Terminado. Se preenchido com true a SMS será enviada; se preenchido com false a SMS não será enviada; se não for preenchido, irá assumir o valor definido no tipo de documento. Esta funcionalidade só funciona se tiver SMS disponíveis.

force_sign boolean

Determina se deve ou não assinar o documento caso o estado do documento seja Terminado e caso o mesmo seja impresso. Se preenchido com true o documento será assinado; se preenchido com false o documento não será assinado; se não for preenchido, irá assumir o valor definido no tipo de documento. Esta funcionalidade só funciona se tiver a Assinatura Digital activada e bem configurada.

status string required

Estado do documento. Deve ser enviado um dos seguintes valores: Rascunho ou Terminado.

Request POST /receipts/create
{
    "issue_date": ..
    "receipt_date": ..
    ...
    "sales": 
    [
        {
        "id": ..,
        "percentage_discount": ..
        "unit_discount": ..
        "total_paid": ..
        }
    ],
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "number": ..,
        "issue_date": ..,
        "receipt_date": ..,
        "serie_id": ..,
        "document_type_id": ..,
        "total_discount": ..,
        "total_balance": ..,
        "total_paid": ..,
        "grand_total": ..,
        "customer_id": ..,
        "customer_code": ..,
        "customer_name": ..,
        "customer_vat_number": ..,
        "customer_country": ..,
        "customer_city": ..,
        "customer_address": ..,
        "customer_postal_code": ..,
        "company_name": ..,
        "company_vat_number": ..,
        "company_country": ..,
        "company_address": ..,
        "company_city": ..,
        "company_postal_code": ..,
        "company_vat_scheme": ..,
        "payment_method_id": ..,
        "currency_id": ..,
        "currency_exchange": ..,
        "location_origin_id": ..,
        "location_origin_name": ..,
        "location_origin_country": ..,
        "location_origin_address": ..,
        "location_origin_city": ..,
        "location_origin_postal_code": ..,
        "observations": ..,
        "url_file": ..,
        "file_previewed": ..,
        "file_last_generated": ..,
        "status": ..,
        "status_last_change": ..,
        "created_by": ..,
        "finished_by": ..,
        "canceled_by": ..,
        "canceled_at": ..,
        "canceled_reason": ..,
        "updated_at": ..,
        "created_at": ..,
        "serie": [],
        "documenttype": [],
        "documenttypeserie": [],
        "paymentmethod": [],
        "currency": [],
        "sales": [],
        "createdby": [],
        "finishedby": [],
        "canceledby": [],
        "customercountry": [],
    }
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • Não preencheu todos os campos obrigatórios
  • O tipo de documento não existe ou não se encontra activo
  • Não preencheu a série ou não existe nenhuma série pré-definida para utilizar
  • Não preencheu a moeda ou não existe nenhuma moeda pré-definida para utilizar
  • Não tem permissões para executar esta operação
  • Seleccione pelo menos um documento
  • O recibo tem um limite máximo de 100 documentos
  • O cliente não existe
  • O cliente não se encontra activo
  • O estado do documento não é válido
  • A série não se encontra atribuída no tipo de documento seleccionado
  • A série não se encontra activa no tipo de documento seleccionado
  • A série encontra-se expirada
  • A série não se encontra comunicada à AT no tipo de documento seleccionado. A partir de 2023 passou a ser um requisito obrigatório
  • O local não existe ou não se encontra activo
  • Um ou mais documentos mal preenchidos, na linha: X
  • O documento não existe
  • Não preencheu todos os campos obrigatórios nos documentos
  • Não preencheu correctamente o valor pago (formato aceite: 0,00 ou 0.00)
  • Não preencheu correctamente a desconto unitário (formato aceite: 0,00 ou 0.00)
  • Não preencheu correctamente a desconto percentual (formato aceite: 0,00 ou 0.00)
  • Não pode saldar um documento com um valor superior ao que está em aberto
  • Formato/valor de câmbio inválido
  • A data emissão não contêm um formato válido (ano-mês-dia)
  • A data de recebimento não contêm um formato válido (ano-mês-dia)
  • Despacho n.º 8632/2014: Quando acontecer uma situação de erro ou anomalia (...) devem ser encerradas as séries em utilização. A série encontra-se bloqueada
  • Já existe um documento do mesmo tipo e da mesma série emitido com uma data superior à data de emissão escolhida

Recibos Actualizar

Apenas pode ser utilizado caso o documento se encontre em rascunho.

issue_date date required

Data de emissão do documento

receipt_date date required

Data de recebimento do documento

document_type mixed required

Tipo de documento. Pode ser enviado o ID ou o descritivo, exemplo: Recibo de Cliente.

serie mixed

Série. Pode ser enviado o ID ou o descritivo, exemplo: 2021, 2021A, etc. No caso de não preenchimento será assumido a série pré-definida.

customer integer required

ID do cliente

vat_number string

Contribuinte do cliente. No caso de não preenchimento será assumido o valor 999999990.

address string required

Morada do cliente

city string required

Localidade do cliente

postal_code string required

Código postal do cliente

country string required

País do cliente

payment_method mixed

Forma de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: Numerário, Transferência bancária, etc.

currency mixed

Moeda utilizada. Pode ser enviado o ID, símbolo ou descritivo, exemplo: , $, Euro, Dólar. No caso de não preenchimento será assumido a moeda pré-definida.

currency_exchange double

Câmbio da moeda. Caso não seja enviado será assumido 1.

observations string

Observações do documento

location_origin mixed

Local de origem. Pode ser enviado o ID ou nome do local. No caso de não preenchimento será assumido o local de origem pré-definido.

sales json array required

Lista de vendas que constam no documento.

id integer required

ID da venda

percentage_discount double

Desconto percentual

unit_discount double

Desconto unitário

total_paid double required

Valor pago

language string

Idioma a ser impresso caso o estado do documento seja Terminado. Preencher com PT ou EN. No caso de não preenchimento será assumido o idioma pré-definido.

format string

Formato a ser impresso caso o estado do documento seja Terminado. Preencher com A4 ou POS. No caso de não preenchimento será assumido o valor definido no tipo de documento (que por norma é A4).

paper_size integer

Tamanho / largura do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_left_margin integer

Margem à esquerda do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_right_margin integer

Margem à direita do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_top_margin integer

Margem em cima do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_bottom_margin integer

Margem em baixo do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

force_print boolean

Se deve forçar a impressão do documento caso o estado do documento seja Terminado. No caso de não preenchimento será assumido o valor definido no tipo de documento (que por norma é Sim).

force_print boolean

Determina se deve ou não gerar a impressão do documento caso o estado do mesmo seja Terminado. Se preenchido com true o documento será impresso; se preenchido com false o documento não será impresso; se não for preenchido, irá assumir o valor definido no tipo de documento.

force_send_email boolean

Determina se deve ou não enviar via email o documento para o cliente caso o estado do mesmo seja Terminado. Se preenchido com true o documento será enviado; se preenchido com false o documento não será enviado; se não for preenchido, irá assumir o valor definido no tipo de documento.

force_send_sms boolean

Determina se deve ou não enviar SMS para o cliente caso o estado do documento seja Terminado. Se preenchido com true a SMS será enviada; se preenchido com false a SMS não será enviada; se não for preenchido, irá assumir o valor definido no tipo de documento. Esta funcionalidade só funciona se tiver SMS disponíveis.

force_sign boolean

Determina se deve ou não assinar o documento caso o estado do documento seja Terminado e caso o mesmo seja impresso. Se preenchido com true o documento será assinado; se preenchido com false o documento não será assinado; se não for preenchido, irá assumir o valor definido no tipo de documento. Esta funcionalidade só funciona se tiver a Assinatura Digital activada e bem configurada.

status string required

Estado do documento. Deve ser enviado um dos seguintes valores: Rascunho ou Terminado.

Request POST /receipts/:id/update
{
    "issue_date": ..
    "receipt_date": ..
    ...
    "sales": 
    [
        {
            "id": ..,
            "percentage_discount": ..
            "unit_discount": ..
            "total_paid": ..
        }
    ],
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "number": ..,
        "issue_date": ..,
        "receipt_date": ..,
        "serie_id": ..,
        "document_type_id": ..,
        "total_discount": ..,
        "total_balance": ..,
        "total_paid": ..,
        "grand_total": ..,
        "customer_id": ..,
        "customer_code": ..,
        "customer_name": ..,
        "customer_vat_number": ..,
        "customer_country": ..,
        "customer_city": ..,
        "customer_address": ..,
        "customer_postal_code": ..,
        "company_name": ..,
        "company_vat_number": ..,
        "company_country": ..,
        "company_address": ..,
        "company_city": ..,
        "company_postal_code": ..,
        "company_vat_scheme": ..,
        "payment_method_id": ..,
        "currency_id": ..,
        "currency_exchange": ..,
        "location_origin_id": ..,
        "location_origin_name": ..,
        "location_origin_country": ..,
        "location_origin_address": ..,
        "location_origin_city": ..,
        "location_origin_postal_code": ..,
        "observations": ..,
        "url_file": ..,
        "file_previewed": ..,
        "file_last_generated": ..,
        "status": ..,
        "status_last_change": ..,
        "created_by": ..,
        "finished_by": ..,
        "canceled_by": ..,
        "canceled_at": ..,
        "canceled_reason": ..,
        "updated_at": ..,
        "created_at": ..,
        "serie": [],
        "documenttype": [],
        "documenttypeserie": [],
        "paymentmethod": [],
        "currency": [],
        "sales": [],
        "createdby": [],
        "finishedby": [],
        "canceledby": [],
        "customercountry": [],
    }
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • O valor do campo id é inválido
  • O tipo de documento não existe ou não se encontra activo
  • Não preencheu a série ou não existe nenhuma série pré-definida para utilizar
  • Não preencheu a moeda ou não existe nenhuma moeda pré-definida para utilizar
  • Não tem permissões para executar esta operação
  • Seleccione pelo menos um documento
  • O recibo tem um limite máximo de 100 documentos
  • O cliente não existe
  • O cliente não se encontra activo
  • O estado do documento não é válido
  • A série não se encontra atribuída no tipo de documento seleccionado
  • A série não se encontra activa no tipo de documento seleccionado
  • A série encontra-se expirada
  • A série não se encontra comunicada à AT no tipo de documento seleccionado. A partir de 2023 passou a ser um requisito obrigatório
  • O local não existe ou não se encontra activo
  • Um ou mais documentos mal preenchidos, na linha: X
  • O documento não existe
  • Não preencheu todos os campos obrigatórios nos documentos
  • Não preencheu correctamente o valor pago (formato aceite: 0,00 ou 0.00)
  • Não preencheu correctamente a desconto unitário (formato aceite: 0,00 ou 0.00)
  • Não preencheu correctamente a desconto percentual (formato aceite: 0,00 ou 0.00)
  • Não pode saldar um documento com um valor superior ao que está em aberto
  • Formato/valor de câmbio inválido
  • A data emissão não contêm um formato válido (ano-mês-dia)
  • A data de recebimento não contêm um formato válido (ano-mês-dia)
  • Despacho n.º 8632/2014: Quando acontecer uma situação de erro ou anomalia (...) devem ser encerradas as séries em utilização. A série encontra-se bloqueada
  • Já existe um documento do mesmo tipo e da mesma série emitido com uma data superior à data de emissão escolhida

Recibos Eliminar

Apenas pode ser utilizado caso o documento se encontre em rascunho.

Request POST /receipts/:id/delete
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação

Recibos Cancelar

Apenas pode ser utilizado caso o documento se encontre terminado e ainda não tenha sido cancelado.

reason string required minimum 15 chars

Justificação da anulação do documento

Request POST /receipts/:id/cancel
{
    "reason": ..,
}
Response 200
{
    "status": true,
    "url_file": ...
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • É obrigatório o preenchimento da razão

Recibos Download

Apenas pode ser utilizado caso o documento se encontre terminado.

language string

Idioma a imprimir o documento. Preencher com PT ou EN. No caso de não preenchimento será assumido o idioma pré-definido.

format string

Formato a ser impresso caso o estado do documento seja Terminado. Preencher com A4 ou POS. No caso de não preenchimento será assumido o formato pré-definido (que por norma é A4).

paper_size integer

Tamanho / largura do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_left_margin integer

Margem à esquerda do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_right_margin integer

Margem à direita do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_top_margin integer

Margem em cima do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

paper_bottom_margin integer

Margem em baixo do documento. Apenas deve ser preenchido caso o formato seja POS. No caso de não preenchimento será assumido o valor definido no tipo de documento.

Request POST /receipts/:id/download
{
    "language": ..,
    "format": ..,
}
Response 200
{
    "status": true,
    "url_file": ...
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação

Recibos Enviar email

Apenas pode ser utilizado caso o documento se encontre terminado.

subject string

Assunto do email. No caso de não preenchimento será assumido o assunto no template.

message string

Corpo do email. No caso de não preenchimento será assumido o corpo do email no template.

to json required

Para quem vai enviar o email

name string required

Nome

email string required

Email

cc string

Cópia do email em CC para N emails. Valores separados por vírgula.

attachments json array

Permite adicionar 2 anexos adicionais. As extensões dos ficheiros autorizadas são: png, jpg, jpeg, bmp, pdf, doc, docx, xls, xlsx, zip, 7z, rar, csv, txt, xml,

filename string required

Nome do ficheiro

url string required

URL do ficheiro

Request POST /receipts/:id/send_email
{
    "subject": ..,
    "message": ..,
    "to": { "name": .., "email": .. },
    "cc": email1,email2,
    "attachments": [{ "filename": .., "url": ..}]
}
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Não preencheu todos os campos obrigatórios
  • Um ou mais emails são inválidos
  • Só é permitido no máximo 2 anexos
  • O anexo adicionado aparenta ser inválido
  • A extensão do anexo adicionado é inválida
  • O URL do anexo adicionado é inválido
  • Não foi possível enviar o email, por favor tente mais tarde. Se o problema persistir, entre em contacto com o suporte

Recibos Enviar sms

Apenas pode ser utilizado caso o documento se encontre terminado.

to json array required

Um ou mais nº de telemóvel

name string required

Nome

mobile string required

Nº de telemóvel. Sem espaços, sem +351, nº nacional.

message string

Mensagem a enviar. No caso de não preenchimento será assumido a mensagem no template.

Request POST /receipts/:id/send_sms
{
    "to": 
    [
        {
            "name": ..,
            "mobile": ..
        }
    ],
    "message": ..
}
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Não preencheu todos os campos obrigatórios
  • Obrigatório o preenchimento do nome
  • Obrigatório o preenchimento do telemóvel
  • O telemóvel é inválido
  • Precisa de configurar primeiro o nome do remetente e o documento de identificação
  • Ainda não foi aprovado o envio de SMS a partir do remetente configurado. Por favor aguarde por um email nosso ou consulte diariamente as configurações para saber o estado em que se encontra o pedido.
  • Não possui SMS disponíveis suficientes

Recibos Assinar digitalmente

Apenas pode ser utilizado caso o documento se encontre terminado.

Request POST /receipts/:id/sign
Sem parâmetros
Response 200
{
    "status": true,
    "url_file": ..
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • O documento já se encontra digitalmente assinado
  • Não existe nenhuma configuração de assinatura digital ou a mesma encontra-se com erros
  • Não foi possível assinar o documento. Consulte a página da assinatura digital para visualizar o erro

Recibos Sumário

Permite calcular em tempo real os totais (total geral, total em saldo, etc) que vão ser emitidos no documento.

document_type mixed required

Tipo de documento. Pode ser enviado o ID ou o descritivo, exemplo: Recibo de Cliente.

currency mixed

Moeda utilizada. Pode ser enviado o ID, símbolo ou descritivo, exemplo: , $, Euro, Dólar. No caso de não preenchimento será assumido a moeda pré-definida.

currency_exchange double

Câmbio da moeda. Caso não seja enviado será assumido 1.

sales json array required

Lista de vendas que constam no documento.

id integer required

ID da venda

percentage_discount double

Desconto percentual

unit_discount double

Desconto unitário

total_paid double required

Valor pago

Request POST /receipts/summary
{
    "document_type": ..,
    "currency": ..,
    "currency_exchange": ..,
    "sales": 
    [
        {
            "id": ..,
            "percentage_discount": ..
            "unit_discount": ..
            "total_paid": ..
        }
    ],
}
Response 200
{
    "status":true,
    "data":
    {
        "grand_total": ..,
        "grand_total_with_currency_exchange": ..,
        "total_balance": ..,
        "total_discount": ..,
        "total_paid": ..,
        "sales": 
        [
            {
                "sale_id": ..,
                "receipt_id": ..,
                "grand_total": ..
                "percentage_discount": ..
                "total_balance": ..
                "total_paid": ..
                "unit_discount": ..
            }
        ],
    }
}

Recibos Procurar

Permite procurar por um recibo.

value mixed required

Valor a procurar

search_in string required

Determina em que campo deve ser procurado. Deve ser enviado um dos seguintes valores: ID, Document Number. No caso da procura ser efectuada no nº do documento, a seguinte nomenclatura exemplo deve ser enviada: RG A/4921.

Request POST /receipts/find
{
    "value": ..,
    "search_in": ..
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "number": ..,
        "issue_date": ..,
        "receipt_date": ..,
        ...
    }
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • O valor do campo value é obrigatório
  • O valor do campo search_in é inválido
  • Não tem permissões para executar esta operação

Recibos Lista

Devolve a lista de recibos. Devolve no máximo 15 resultados.

value mixed

Valor a procurar

search_in string

Determina em que campo deve ser procurado. Pode ser enviado um dos seguintes valores: ID, Document Number, Customer, Vat Number. No caso da procura ser efectuada no nº do documento, a seguinte nomenclatura exemplo deve ser enviada: FT A/4921.

skip integer

Determina que indice deve saltar. Deve ser enviado um valor multiplicador de 15.

Request POST /receipts/list
{
    "value": ..,
    "search_in": ..
    "skip": ..
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "number": ..,
        "issue_date": ..,
        "receipt_date": ..,
        ...
    }
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • Não tem permissões para executar esta operação

Clientes

Este endpoint visa gerir os clientes.

Endpoints
POST /customers/create
POST /customers/:id/update
POST /customers/:id/delete
POST /customers/find
POST /customers/list
POST /customers/:id/accounts_open
POST /customers/:id/accounts_open/download
POST /customers/:id/accounts_open/send_email
POST /customers/accounts_open

Clientes Criar

O cliente é sempre criado no estado activo.

code string

Código do cliente. Se não for enviado nenhum valor vai ser dado seguimento ao último código ou gerado um código aleatório.

name string required

Nome

vat_number string

Contribuinte

country string

País

address string

Morada

city string

Localidade

postal_code string

Código postal

email string

Email

telephone string

Telefone

mobile string

Telemóvel. Evite espaços e +351.

currency mixed

Moeda utilizada. Pode ser enviado o ID, símbolo ou descritivo, exemplo: , $, Euro, Dólar. No caso de não preenchimento será assumido a moeda pré-definida.

payment_method mixed

Forma de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: Numerário, Transferência bancária, etc.

payment_condition mixed

Condição de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: Pronto pagamento, 30 dias, etc.

shipping_mode mixed

Modo de expedição. Pode ser enviado o ID ou o descritivo, exemplo: Correios, Comboio, etc.

price mixed

Tabela de preços utilizada. Pode ser enviado o ID ou o descritivo, exemplo: Preços público, Preços revenda, etc.

employee mixed

Vendedor que adquiriu o cliente. Pode ser enviado o ID ou o email.

type string required

Tipo de cliente. Deve ser enviado um dos seguintes valores: Empresarial, Particular.

vat_type string required

Tipo de IVA. Deve ser enviado um dos seguintes valores: Debitar IVA, IVA incluído, Não fazer nada.

vat_exemption mixed

Isenção de IVA a aplicar. Pode ser enviado o ID ou o código, exemplo: M08, etc. No caso de não preenchimento será assumido o valor M18 - Sem isenção.

irs_retention_tax double

Taxa de retenção na fonte

observations string

Observações do cliente

contact string

Outros contactos

other_emails string

Outros emails. Emails separados por vírgula.

receive_sms boolean

Determina se o cliente está apto a receber notificações de SMS despoletadas automaticamente

receive_emails boolean

Determina se o cliente está apto a receber notificações de Emails despoletadas automaticamente

language string

Determina o idioma por defeito no cliente. Deve ser enviado um dos seguintes valores: Auto, PT, EN. No caso de não preenchimento será assumido Auto.

addresses json array

Lista de moradas de entrega.

country string

País

address string

Morada

city string

Localidade

postal_code string

Código postal

Request POST /customers/create
{
    "code": ..,
    "name": ..,
    "vat_number": ..,
    "country": ..,
    "address": ..,
    "city": ..,
    "postal_code": ..,
    "email": ..
    "telephone": ..,
    "mobile": ..,
    "currency": ..,
    "payment_method": ..,
    "payment_condition": ..,
    "shipping_mode": ..,
    "price": ..,
    "employee": ..,
    "type": ..,
    "vat_exemption": ..,
    "vat_type": ..,
    "irs_retention_tax": ..,
    "observations": ..,
    "contact": ..,
    "other_emails": ..,
    "addresses": []
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "code": ..,
        "name": ..,
        "vat_number": ..,
        "country": ..,
        "address": ..,
        "city": ..,
        "postal_code": ..,
        "email": ..
        "telephone": ..,
        "mobile": ..,
        "currency_id": ..,
        "payment_method_id": ..,
        "payment_condition_id": ..,
        "shipping_mode_id": ..,
        "price_id": ..,
        "employee_id": ..,
        "type": ..,
        "vat_exemption_id": ..,
        "vat_type": ..,
        "irs_retention_tax": ..,
        "observations": ..,
        "contact": ..,
        "other_emails": ..,
        "code_blocked": ..,
        "vat_number_blocked": ..,
        "name_blocked": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
        "addresses": []
        "currency": []
        "paymentmethod": []
        "paymentcondition": []
        "shippingmode": []
        "employee": []
        "price": []
        "vatexemption": []
    }
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo código já se encontra registado
  • O contribuinte introduzido aparenta ser inválido para Portugal
  • O valor indicado para o campo Contribuinte já se encontra registado

Clientes Actualizar

code string

Código do cliente. Se não for enviado nenhum valor vai ser dado seguimento ao último código ou gerado um código aleatório.

name string required

Nome

vat_number string

Contribuinte

country string

País

address string

Morada

city string

Localidade

postal_code string

Código postal

email string

Email

telephone string

Telefone

mobile string

Telemóvel. Evite espaços e +351.

currency mixed

Moeda utilizada. Pode ser enviado o ID, símbolo ou descritivo, exemplo: , $, Euro, Dólar. No caso de não preenchimento será assumido a moeda pré-definida.

payment_method mixed

Forma de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: Numerário, Transferência bancária, etc.

payment_condition mixed

Condição de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: Pronto pagamento, 30 dias, etc.

shipping_mode mixed

Modo de expedição. Pode ser enviado o ID ou o descritivo, exemplo: Correios, Comboio, etc.

price mixed

Tabela de preços utilizada. Pode ser enviado o ID ou o descritivo, exemplo: Preços público, Preços revenda, etc.

employee mixed

Vendedor que adquiriu o cliente. Pode ser enviado o ID ou o email.

type string required

Tipo de cliente. Deve ser enviado um dos seguintes valores: Empresarial, Particular.

vat_type string required

Tipo de IVA. Deve ser enviado um dos seguintes valores: Debitar IVA, IVA incluído, Não fazer nada.

vat_exemption mixed

Isenção de IVA a aplicar. Pode ser enviado o ID ou o código, exemplo: M08, etc. No caso de não preenchimento será assumido o valor M18 - Sem isenção.

irs_retention_tax double

Taxa de retenção na fonte

observations string

Observações do cliente

contact string

Outros contactos

other_emails string

Outros emails. Emails separados por vírgula.

active boolean

Estado

receive_sms boolean

Determina se o cliente está apto a receber notificações de SMS despoletadas automaticamente

receive_emails boolean

Determina se o cliente está apto a receber notificações de Emails despoletadas automaticamente

language string

Determina o idioma por defeito no cliente. Deve ser enviado um dos seguintes valores: Auto, PT, EN. No caso de não preenchimento será assumido Auto.

addresses json array

Lista de moradas de entrega.

country string

País

address string

Morada

city string

Localidade

postal_code string

Código postal

Request POST /customers/:id/update
{
    "code": ..,
    "name": ..,
    "vat_number": ..,
    "country": ..,
    "address": ..,
    "city": ..,
    "postal_code": ..,
    "email": ..
    "telephone": ..,
    "mobile": ..,
    "currency": ..,
    "payment_method": ..,
    "payment_condition": ..,
    "shipping_mode": ..,
    "price": ..,
    "employee": ..,
    "type": ..,
    "vat_exemption": ..,
    "vat_type": ..,
    "irs_retention_tax": ..,
    "observations": ..,
    "contact": ..,
    "other_emails": ..,
    "active": ..,
    "addresses": []
}
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo código já se encontra registado
  • O contribuinte introduzido aparenta ser inválido para Portugal
  • O valor indicado para o campo Contribuinte já se encontra registado

Clientes Eliminar

Apenas pode ser utilizado caso o cliente ainda não tenha sido utilizado em nenhum documento.

Request POST /customers/:id/delete
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Este registo não pode ser eliminado

Clientes Procurar

Permite procurar por clientes. Devolve no máximo 15 resultados.

value mixed required

Valor a procurar

search_in string

Determina em que campo deve ser procurado. Pode ser enviado um dos seguintes valores: ID, Code, Name, Email, Vat Number, Mobile.

Request POST /customers/find
{
    "value": ..,
    "search_in": ..
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "code": ..,
            "name": ..,
            "vat_number": ..,
            ...
        }
    ]
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • Não tem permissões para executar esta operação

Clientes Lista

Devolve a lista de clientes. Devolve no máximo 15 resultados.

skip integer

Determina que indice deve saltar. Deve ser enviado um valor multiplicador de 15.

active mixed

Define que estados de clientes deve retornar. Deve ser enviado um dos seguintes valores: true, false, All.

Request POST /customers/list
{
    "skip": ..,
    "active": ..
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "code": ..,
            "name": ..,
            "vat_number": ..,
            ...
        }
    ]
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • Não tem permissões para executar esta operação

Clientes Contas em aberto Por cliente

Devolve a lista de valores em aberto por saldar (documentos de facturação) para um cliente. Essencial para a emissão de recibos.

Request POST /customers/:id/accounts_open
Sem parâmetros
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "sale_id": ..,
            "debit": ..,
            "credit": ..,
            "balance": ..,
            "currency_id": ..,
            "currency_exchange": ..,
            "sale": [],
            "currency": [],
        }
    ]
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • Não tem permissões para executar esta operação

Clientes Contas em aberto Download

Efectua o download em formato PDF A4 do Extracto de Contas em Aberto relativo ao cliente.

date_from date

Data de

date_to date

Data até

Request POST /customers/:id/accounts_open/download
{
    "date_from": ..,
    "date_to": ..
}
Response 200
{
    "status": true,
    "url_file": ..
}
Possíveis erros
  • Não tem permissões para executar esta operação
  • Não existem resultados para exportar

Clientes Contas em aberto Enviar email

Envia via email o PDF A4 do Extracto de Contas em Aberto relativo ao cliente.

subject string required

Assunto do email

message string required

Corpo do email

to json required

Para quem vai enviar o email

name string required

Nome

email string required

Email

cc string

Cópia do email em CC para N emails. Valores separados por vírgula.

Request POST /customers/:id/accounts_open/send_email
{
    "subject": ..,
    "message": ..
    "to": { name: .., email: .. },
    "cc": email1,email2
}
Response 200
{
    "status": true
}
Possíveis erros
  • Não tem permissões para executar esta operação
  • Não preencheu todos os campos obrigatórios
  • Um ou mais emails são inválidos
  • Não existem resultados para exportar
  • Não foi possível enviar o email, por favor tente mais tarde. Se o problema persistir, entre em contacto com o suporte

Clientes Contas em aberto Lista

Devolve a lista de valores em aberto por saldar (documentos de facturação) de todos os clientes.

value mixed

Valor a procurar

search_in string

Determina em que campo deve ser procurado. Pode ser enviado um dos seguintes valores: ID, Code, Name, Email, Vat Number, Mobile.

skip integer

Determina que indice deve saltar. Deve ser enviado um valor multiplicador de 15.

Request POST /customers/accounts_open
{
    "value": ..
    "search_in": ..
    "skip": ..
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "sale_id": ..,
            "debit": ..,
            "credit": ..,
            "balance": ..,
            "currency_id": ..,
            "currency_exchange": ..,
            "sale": [],
            "customer": [],
            "currency": [],
        }
    ]
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • Não tem permissões para executar esta operação

Artigos

Este endpoint visa gerir os artigos.

Endpoints
POST /items/create
POST /items/:id/update
POST /items/:id/delete
POST /items/:id/delete_image
POST /items/find
POST /items/list
POST /items/stock/movements/create
POST /items/stock/movements/:id/update
POST /items/stock/movements/:id/delete
POST /items/:id/stock/actual

Artigos Criar

O artigo é sempre criado no estado activo. Caso decida fazer o upload da imagem, o Content-Type enviado nos Headers deve ser multipart/form-data ou application/x-www-form-urlencoded.

reference string

Referência do artigo. Se não for enviado nenhum valor vai ser dado seguimento à última referência ou gerado uma referência aleatória.

description string required

Descrição

details string

Descrição detalhada do artigo

details_show_print boolean

Se mostra a descrição detalhada na impressão

category integer

Categoria do artigo. Deve ser enviado o ID.

unit integer required

Unidade de medida. Pode ser enviado o ID, descritivo ou símbolo, exemplo: cm, kg, Kilos, etc.

vat mixed required

Taxa de IVA a aplicar. Pode ser enviado o ID, descritivo ou a taxa, exemplo: 23, 13, etc.

vat_exemption mixed

Isenção de IVA a aplicar. Pode ser enviado o ID ou o código, exemplo: M08, etc. No caso de não preenchimento será assumido o valor M18 - Sem isenção.

type string required

Tipo de contabilidade. Deve ser enviado um dos seguintes valores: Embalagens, Matérias primas, Mercadorias, Produtos acabados e intermédios, Serviços, Subprodutos, Transporte, Vasilhame.

cost_price double

Preço de custo do artigo

observations string

Observações do artigo

file file

Imagem do artigo

prices json array

Lista de preços a aplicar

id string

ID da tabela de preços

price double

Preço

discount double

Desconto

barcodes json array

Lista de códigos barras

code string

Código

quantity double

Quantidade

description string

Descrição

minimum_stock json array

Lista de stock mínimo (alerta) por armazém

id string

ID da tabela de armazéns

quantity double

Quantidade

Request POST /items/create
{
    "reference": ..,
    "description": ..,
    "details": ..,
    "details_show_print": ..,
    "category": ..,
    "unit": ..,
    "vat": ..,
    "vat_exemption": ..
    "type": ..,
    "cost_price": ..,
    "observations": ..,
    "prices": []
    "barcodes": []
    "minimum_stock": []
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "reference": ..,
        "description": ..,
        "details": ..,
        "details_show_print": ..,
        "category_id": ..,
        "unit_id": ..,
        "vat_id": ..,
        "vat_exemption_id": ..
        "type": ..,
        "cost_price": ..,
        "observations": ..,
        "url_image": ..,
        "reference_blocked": ..,
        "description_blocked": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
        "category": []
        "prices": []
        "barcodes": []
        "averagecostprices": []
        "minimumstock": []
    }
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo referência já se encontra registado
  • O valor indicado para o campo descrição já se encontra registado
  • O formato da imagem não é válido
  • O tamanho da imagem não pode ser superior a 3MB

Artigos Actualizar

Caso decida fazer o upload da imagem, o Content-Type enviado nos Headers deve ser multipart/form-data ou application/x-www-form-urlencoded.

reference string

Referência do artigo. Se não for enviado nenhum valor vai ser dado seguimento à última referência ou gerado uma referência aleatória.

description string required

Descrição

details string

Descrição detalhada do artigo

details_show_print boolean

Se mostra a descrição detalhada na impressão

category integer

Categoria do artigo. Deve ser enviado o ID.

unit integer required

Unidade de medida. Pode ser enviado o ID, descritivo ou símbolo, exemplo: cm, kg, Kilos, etc.

vat mixed required

Taxa de IVA a aplicar. Pode ser enviado o ID, descritivo ou a taxa, exemplo: 23, 13, etc.

vat_exemption mixed

Isenção de IVA a aplicar. Pode ser enviado o ID ou o código, exemplo: M08, etc. No caso de não preenchimento será assumido o valor M18 - Sem isenção.

type string required

Tipo de contabilidade. Deve ser enviado um dos seguintes valores: Embalagens, Matérias primas, Mercadorias, Produtos acabados e intermédios, Serviços, Subprodutos, Transporte, Vasilhame.

cost_price double

Preço de custo do artigo

observations string

Observações do artigo

file file

Imagem do artigo

active boolean

Estado

prices json array

Lista de preços a aplicar

id string

ID da tabela de preços

price double

Preço

discount double

Desconto

barcodes json array

Lista de códigos barras

code string

Código

quantity double

Quantidade

description string

Descrição

minimum_stock json array

Lista de stock mínimo (alerta) por armazém

id string

ID da tabela de armazéns

quantity double

Quantidade

Request POST /items/:id/update
{
    "reference": ..,
    "description": ..,
    "details": ..,
    "details_show_print": ..,
    "category_id": ..,
    "unit": ..,
    "vat": ..,
    "vat_exemption": ..
    "type": ..,
    "cost_price": ..,
    "observations": ..,
    "prices": []
    "barcodes": []
    "minimum_stock": []
}
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo código já se encontra registado

Artigos Eliminar

Apenas pode ser utilizado caso o artigo ainda não tenha sido utilizado em nenhum documento.

Request POST /items/:id/delete
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Este registo não pode ser eliminado

Artigos Eliminar imagem

Elimina a imagem do artigo.

Request POST /items/:id/delete_image
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação

Artigos Procurar

Permite procurar por artigos. Devolve no máximo 15 resultados.

value mixed required

Valor a procurar

search_in string

Determina em que campo deve ser procurado. Pode ser enviado um dos seguintes valores: ID, Reference, Description, Barcode.

Este endpoint devolve o total em stock do artigo para todos os armazéns.

Request POST /items/find
{
    "value": ..,
    "search_in": ..
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "reference": ..,
            "description": ..,
            "details": ..,
            ...
        }
    ]
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • Não tem permissões para executar esta operação

Artigos Lista

Devolve a lista de artigos. Devolve no máximo 15 resultados.

skip integer

Determina que indice deve saltar. Deve ser enviado um valor multiplicador de 15.

active mixed

Define que estados de artigos deve retornar. Deve ser enviado um dos seguintes valores: true, false, All.

Este endpoint devolve o total em stock do artigo para todos os armazéns.

Request POST /items/list
{
    "skip": ..,
    "active": ..
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "reference": ..,
            "description": ..,
            "details": ..,
            ...
        }
    ]
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • Não tem permissões para executar esta operação

Artigos Stock Movimentos - Criar

Cria um novo movimento de stock.

warehouse mixed required

Armazém. Pode ser enviado o ID ou o descritivo.

item mixed required

Artigo. Pode ser enviado o ID ou a referência. Obrigatoriamente deve ser um artigo do tipo Mercadorias.

date date required

Data do movimento

type string required

Tipo de movimento. Deve ser enviado um dos seguintes valores: Entrada, Saída.

quantity double required

Quantidade de stock

unit_price double

Preço unitário

Request POST /items/stock/movements/create
{
    "warehouse": ..,
    "item": ..
    "date": ..
    "type": ..
    "quantity": ..
    "unit_price": ..
}
Response 200
{
    "status": true,
    "id": ..
}
Possíveis erros
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O artigo não existe ou não se trata de um artigo do tipo Mercadorias
  • O armazém não existe

Artigos Stock Movimentos - Actualizar

Actualiza um movimento de stock existente. Tem repercussões nos Preços Médios de Custo. Apenas é possível actualizar movimentos de stock que foram criados manualmente.

warehouse mixed required

Armazém. Pode ser enviado o ID ou o descritivo.

item mixed required

Artigo. Pode ser enviado o ID ou a referência. Obrigatoriamente deve ser um artigo do tipo Mercadorias.

date date required

Data do movimento

type string required

Tipo de movimento. Deve ser enviado um dos seguintes valores: Entrada, Saída.

quantity double required

Quantidade de stock

unit_price double

Preço unitário

Request POST /items/stock/movements/:id/update
{
    "warehouse": ..,
    "item": ..
    "date": ..
    "type": ..
    "quantity": ..
    "unit_price": ..
}
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O artigo não existe ou não se trata de um artigo do tipo Mercadorias
  • O armazém não existe

Artigos Stock Movimentos - Eliminar

Elimina um movimento de stock existente. Tem repercussões nos Preços Médios de Custo. Apenas é possível eliminar movimentos de stock que foram criados manualmente.

Request POST /items/stock/movements/:id/delete
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação

Artigos Stock actual

Obtém o stock actual para determinado artigo. O endpoint devolve a soma (total) bem como as estatísticas do ano mencionado.

warehouse mixed

Armazém. Pode ser enviado o ID ou o descritivo. No caso de não preenchimento será devolvido o stock de todos os armazéns.

year integer

Ano do stock. No caso de não preenchimento será assumido o ano actual.

O valor do campo devolvido stats_year é um array multidimensional onde consta o total de entradas, total de saídas e balanço, por esta ordem.

Request POST /items/:id/stock/actual
{
    "warehouse": ..,
    "year": ..
}
Response 200
{
    "status": true,
    "data":
    [
        {
            "quantity_in": ..,
            "quantity_out": ..,
            "balance": ..,
            "average_cost_price": ..,
            "stats_year": ..,
            "warehouse": ..
        }
    ]
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • O armazém não existe

Marcações

Este endpoint visa gerir as marcações na agenda.

Endpoints
POST /bookings/create
POST /bookings/:id/update
POST /bookings/:id/update/time
POST /bookings/:id/delete
POST /bookings/:id/invoice/create
POST /bookings/check_availability
POST /bookings/summary
POST /bookings/find
POST /bookings/list

Agenda - Marcações Criar

customer integer required

ID do cliente

vat_number string

Contribuinte do cliente. No caso de não preenchimento será assumido o valor 999999990.

start_at datetime required

Data de início da marcação, no formato ano-mes-dia horas:minutos

end_at datetime required

Data de fim da marcação, no formato ano-mes-dia horas:minutos

ignore_validations boolean

Se deve ignorar validações da hora da marcação, como por exemplo a data seleccionada já se encontrar ocupada

description string

Descrição da marcação. Se preenchido irá sobrepor-se ao nome do cliente na agenda.

location mixed

Local da marcação. Pode ser enviado o ID ou nome do local. No caso de não preenchimento será assumido o local pré-definido.

employee mixed

Colaborador a quem está atribuída a marcação. Pode ser enviado o ID ou o email.

payment_method mixed

Forma de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: Numerário, Transferência bancária, etc.

status string required

Estado da marcação. Deve ser enviado um dos seguintes valores: Pendente ou Confirmado.

paid boolean

Determina se a marcação se encontra paga

observations string

Observações da marcação

items json array required

Lista de artigos que constam na marcação.

id mixed required

ID ou referência do artigo

price double required

Preço unitário

quantity double required

Quantidade

discount double

Desconto percentual

Request POST /bookings/create
{
    "customer": ..,
    "vat_number": ..
    "start_at": ..
    "end_at": ..
    "ignore_validations": ..
    "description": ..
    "location": ..
    "employee": ..
    "payment_method": ..
    "status": ..
    "paid": ..
    "observations": ..
    "items": 
    [
        {
            "id": ..,
            "price": ..
            "quantity": ..
            "discount": ..
        }
    ],
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "number": ..,
        "description": ..,
        "sale_id": ..,
        "location_id": ..,
        "customer_id": ..,
        "customer_vat_number": ..,
        "employee_id": ..,
        "payment_method_id": ..,
        "start_at": ..,
        "end_at": ..,
        "ignore_validations": ..,
        "gross_total": ..,
        "total_discount": ..,
        "net_total": ..,
        "total_vat": ..,
        "grand_total": ..,
        "sms_alert_sent": ..,
        "email_alert_sent": ..,
        "email_invoice_sent": ..,
        "paid": ..,
        "paid_at": ..,
        "status": ..,
        "observations": ..,        
        "created_by": ..,        
        "updated_at": ..,
        "created_at": ..,
        "sale": [],
        "customer": [],
        "location": [],
        "employee": [],
        "paymentmethod": [],        
        "items": [],
        "createdby": [],
    }
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • Não tem permissões para executar esta operação
  • Não preencheu todos os campos obrigatórios
  • A data início ou fim não contêm um formato válido (ano-mês-dia horas:minutos)
  • A data início não pode ser inferior à data actual
  • A data início e fim não se encontra dentro do horário da agenda configurado
  • A data / hora fim não pode ser inferior à data início
  • O estado introduzido não existe
  • Seleccione pelo menos um artigo
  • A marcação tem o limite máximo de 20 artigos
  • O cliente não existe
  • O cliente não se encontra activo
  • A data da marcação encontra-se ocupada
  • Um ou mais artigos mal preenchidos, na linha: X
  • O artigo não existe
  • Não preencheu todos os campos obrigatórios nos artigos
  • Não preencheu correctamente o preço unitário (formato aceite: 0,00000 ou 0.00000)
  • Não preencheu correctamente a quantidade (formato aceite: 0,00000 ou 0.00000)
  • Não preencheu correctamente o desconto (formato aceite: 0,00 ou 0.00)
  • O total não pode ser negativo ou igual a zero

Agenda - Marcações Actualizar

customer integer required

ID do cliente

vat_number string

Contribuinte do cliente. No caso de não preenchimento será assumido o valor 999999990.

start_at datetime required

Data de início da marcação, no formato ano-mes-dia horas:minutos

end_at datetime required

Data de fim da marcação, no formato ano-mes-dia horas:minutos

ignore_validations boolean

Se deve ignorar validações da hora da marcação, como por exemplo a data seleccionada já se encontrar ocupada

description string

Descrição da marcação. Se preenchido irá sobrepor-se ao nome do cliente na agenda.

location mixed

Local da marcação. Pode ser enviado o ID ou nome do local. No caso de não preenchimento será assumido o local pré-definido.

employee mixed

Colaborador a quem está atribuída a marcação. Pode ser enviado o ID ou o email.

payment_method mixed

Forma de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: Numerário, Transferência bancária, etc.

status string required

Estado da marcação. Deve ser enviado um dos seguintes valores: Pendente, Confirmado ou Cancelado.

paid boolean

Determina se a marcação se encontra paga

observations string

Observações da marcação

items json array required

Lista de artigos que constam na marcação.

id mixed required

ID ou referência do artigo

price double required

Preço unitário

quantity double required

Quantidade

discount double

Desconto percentual

Request POST /bookings/:id/update
{
    "customer": ..,
    "vat_number": ..
    "start_at": ..
    "end_at": ..
    "ignore_validations": ..
    "description": ..
    "location": ..
    "employee": ..
    "payment_method": ..
    "status": ..
    "paid": ..
    "observations": ..
    "items": 
    [
        {
            "id": ..,
            "price": ..
            "quantity": ..
            "discount": ..
        }
    ],
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "number": ..,
        "description": ..,
        "sale_id": ..,
        "location_id": ..,
        "customer_id": ..,
        "customer_vat_number": ..,
        "employee_id": ..,
        "payment_method_id": ..,
        "start_at": ..,
        "end_at": ..,
        "ignore_validations": ..,
        "gross_total": ..,
        "total_discount": ..,
        "net_total": ..,
        "total_vat": ..,
        "grand_total": ..,
        "sms_alert_sent": ..,
        "email_alert_sent": ..,
        "email_invoice_sent": ..,
        "paid": ..,
        "paid_at": ..,
        "status": ..,
        "observations": ..,        
        "created_by": ..,        
        "updated_at": ..,
        "created_at": ..,
        "sale": [],
        "customer": [],
        "location": [],
        "employee": [],
        "paymentmethod": [],        
        "items": [],
        "createdby": [],
    }
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Não preencheu todos os campos obrigatórios
  • A data início ou fim não contêm um formato válido (ano-mês-dia horas:minutos)
  • A data início não pode ser inferior à data actual
  • A data início e fim não se encontra dentro do horário da agenda configurado
  • A data / hora fim não pode ser inferior à data início
  • O estado introduzido não existe
  • Seleccione pelo menos um artigo
  • A marcação tem o limite máximo de 20 artigos
  • O cliente não existe
  • O cliente não se encontra activo
  • A data da marcação encontra-se ocupada
  • Um ou mais artigos mal preenchidos, na linha: X
  • O artigo não existe
  • Não preencheu todos os campos obrigatórios nos artigos
  • Não preencheu correctamente o preço unitário (formato aceite: 0,00000 ou 0.00000)
  • Não preencheu correctamente a quantidade (formato aceite: 0,00000 ou 0.00000)
  • Não preencheu correctamente o desconto (formato aceite: 0,00 ou 0.00)
  • O total não pode ser negativo ou igual a zero

Agenda - Marcações Actualizar data

start_at datetime required

Data de início da marcação, no formato ano-mes-dia horas:minutos

end_at datetime required

Data de fim da marcação, no formato ano-mes-dia horas:minutos

ignore_validations boolean

Se deve ignorar validações da hora da marcação, como por exemplo a data seleccionada já se encontrar ocupada

Request POST /bookings/:id/update/time
{
    "start_at": ..
    "end_at": ..
    "ignore_validations": ..
}
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Não preencheu todos os campos obrigatórios
  • A data início ou fim não contêm um formato válido (ano-mês-dia horas:minutos)
  • A data início não pode ser inferior à data actual
  • A data início e fim não se encontra dentro do horário da agenda configurado
  • A data / hora fim não pode ser inferior à data início
  • A data da marcação encontra-se ocupada

Agenda - Marcações Eliminar

Apenas pode ser utilizado caso ainda não haja documento associado / emitido.

Request POST /bookings/:id/delete
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • A marcação não pode ser eliminada por já ter um documento associado

Agenda - Marcações Criar documento

Apenas pode ser utilizado caso a marcação se encontre paga.

send_email boolean

Se deve enviar email para o cliente

to json

Para quem vai enviar o email

name string required

Nome

email string required

Email

cc string

Cópia do email em CC para N emails. Valores separados por vírgula.

Request POST /bookings/:id/invoice/create
{
    "send_email": ..
    "to": { "name": .., "email": .. }
    "cc": email1,email2
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "number": ..,
        "issue_date": ..,
        "due_date": ..,
        "serie_id": ..,
        "document_type_id": ..,
        ...
    }
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Existem campos por configurar na agenda
  • Já existe um documento associado à marcação
  • A marcação não se encontra paga
  • A marcação não se encontra no estado confirmado
  • Não preencheu todos os campos obrigatórios
  • Um ou mais emails são inválidos

Agenda - Marcações Verificar disponibilidade

start_at datetime required

Data de início da marcação, no formato ano-mes-dia horas:minutos

end_at datetime required

Data de fim da marcação, no formato ano-mes-dia horas:minutos

location mixed

Local da marcação. Pode ser enviado o ID ou nome do local. No caso de não preenchimento será assumido o local pré-definido.

employee mixed

Colaborador a quem está atribuída a marcação. Pode ser enviado o ID ou o email.

Request POST /bookings/check_availability
{
    "start_at": ..,
    "end_at": ..,
    "employee": ..,
    "location": ..,
}
Response 200
{
    "status": true,
    "is_available": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não preencheu todos os campos obrigatórios

Agenda - Marcações Sumário

Permite calcular em tempo real os totais (total de iva, total geral, etc) relativos à marcação.

items json array required

Lista de artigos que constam na marcação.

id mixed required

ID ou referência do artigo

price double required

Preço unitário

quantity double required

Quantidade

discount double

Desconto percentual

Request POST /bookings/summary
{
    "items": 
    [
        {
            "id": ..,
            "price": ..
            "quantity": ..
            "discount": ..
        }
    ],
}
Response 200
{
    "status":true,
    "data":
    {
        "gross_total": ..,
        "total_discount": ..,
        "net_total": ..,
        "total_vat": ..,
        "grand_total": ..,       
        "items":
        [
            {
                "item_id": ..,
                "price": ..,
                "quantity": ..,
                "discount": ..,
            }
        ],
    }
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Agenda - Marcações Procurar

Permite procurar por uma marcação.

value mixed required

Valor a procurar

search_in string required

Determina em que campo deve ser procurado. Deve ser enviado um dos seguintes valores: ID ou Document Number. No caso da procura ser efectuada no nº do documento, a seguinte nomenclatura exemplo deve ser enviada: FT A/4921.

Request POST /bookings/find
{
    "value": ..,
    "search_in": ..
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "number": ..,
        "description": ..,
        "sale_id": ..,
        "location_id": ..,
        "customer_id": ..,
        ...
    }
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • O valor do campo value é obrigatório
  • O valor do campo search_in é inválido
  • Não tem permissões para executar esta operação

indisponibilidades

Este endpoint visa gerir as indisponibilidades na agenda.

Endpoints
POST /bookings/unavailables/create
POST /bookings/unavailables/:id/update
POST /bookings/unavailables/:id/delete

Agenda - Indisponibilidades Criar

reason string required

Razão da indisponibilidade. Deve ser enviado um dos seguintes valores: Doença, Férias, Almoço, Folga, Outro.

location mixed

Local da marcação. Pode ser enviado o ID ou nome do local. No caso de não preenchimento será assumido o local pré-definido.

employee mixed

Colaborador a quem está atribuída a marcação. Pode ser enviado o ID ou o email.

observations string

Observações da indisponibilidade

dates json array required

Lista de datas que constam na indisponibilidade. Serão geradas tantas indisponibilidades quanto o nº de elementos / datas

start_at datetime required

Data de início da marcação, no formato ano-mes-dia horas:minutos

end_at datetime required

Data de fim da marcação, no formato ano-mes-dia horas:minutos

Request POST /bookings/unavailables/create
{
    "reason": ..,
    "location": ..
    "employee": ..
    "observations": ..
    "dates": 
    [
        {
            "start_at": ..,
            "end_at": ..
        }
    ],
}
Response 200
{
    "status": true,   
    "data": 
    {
        [
            "id": ..,
            "start_at": ..,
            "end_at": ..,
            "reason": ..,
            "observations": ..,
            "employee": [],   
            "location": [],   
        ],
        [
            "id": ..,
            "start_at": ..,
            "end_at": ..,
            "reason": ..,
            "observations": ..,
            "employee": [],   
            "location": [],   
        ],
    }, 
}
Possíveis erros
  • Não tem permissões para executar esta operação
  • Não preencheu todos os campos obrigatórios
  • A data início ou fim não contêm um formato válido (ano-mês-dia horas:minutos)
  • A data / hora fim não pode ser inferior à data início
  • As datas não aparentam estar no formato adequado

Agenda - Indisponibilidades Actualizar

start_at datetime required

Data de início da marcação, no formato ano-mes-dia horas:minutos

end_at datetime required

Data de fim da marcação, no formato ano-mes-dia horas:minutos

reason string required

Razão da indisponibilidade. Deve ser enviado um dos seguintes valores: Doença, Férias, Almoço, Folga, Outro.

location mixed

Local da marcação. Pode ser enviado o ID ou nome do local. No caso de não preenchimento será assumido o local pré-definido.

employee mixed

Colaborador a quem está atribuída a marcação. Pode ser enviado o ID ou o email.

observations string

Observações da indisponibilidade

Request POST /bookings/unavailables/:id/update
{
    "start_at": ..
    "end_at": ..
    "reason": ..
    "location": ..
    "employee": ..
    "observations": ..
}
Response 200
{
    "status": true,
}

Sugerimos que teste e valide a resposta completa numa plataforma de testes de API como por exemplo Postman ou Insomnia.

Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Não preencheu todos os campos obrigatórios
  • A data início ou fim não contêm um formato válido (ano-mês-dia horas:minutos)
  • A data / hora fim não pode ser inferior à data início
  • As datas não aparentam estar no formato adequado

Agenda - Indisponibilidades Eliminar

Request POST /bookings/unavailables/:id/delete
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação

Administração

Este endpoint visa gerir todas as tabelas de auxiliares.

Administração Todos

Devolve a lista de todos os endpoints disponíveis nos menus Administração & Subscrição. Apenas devolve os itens que se encontrem activos e caso possua permissões de leitura.

Request POST /administration/all
Sem parâmetros
Response 200
{
    "status": true,
    "data": 
    {
        "categories": [],
        "countries": [],
        "currencies": [],
        "documents_types": [],
        "employees": [],
        ...
    }
}

Administração - Armazéns Criar

description string required

Descrição

active boolean

Estado

Request POST /administration/warehouses/create
{
    "description": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado

Administração - Armazéns Actualizar

description string required

Descrição

active boolean

Estado

Request POST /administration/warehouses/:id/update
{
    "description": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • O valor do campo id é inválido
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado

Administração - Armazéns Eliminar

Apenas pode ser utilizado caso o armazém ainda não tenha sido utilizado em nenhum documento.

Request POST /administration/warehouses/:id/delete
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Este registo não pode ser eliminado

Administração - Armazéns Procurar

Permite procurar por armazéns.

value mixed required

Valor a procurar

Request POST /administration/warehouses/find
{
    "value": ..,
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Armazéns Lista

Devolve a lista de armazéns.

active mixed

Define que estados de armazéns deve retornar. Deve ser enviado um dos seguintes valores: true, false, All.

Request POST /administration/warehouses/list
{
    "active": ..
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,   
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Categorias Criar

description string required

Descrição

category_id integer

ID da categoria pai

active boolean

Estado

Request POST /administration/categories/create
{
    "description": ..,
    "category_id": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "category_id": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado

Administração - Categorias Actualizar

description string required

Descrição

category_id integer

ID da categoria pai

active boolean

Estado

Request POST /administration/categories/:id/update
{
    "description": ..,
    "category_id": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "category_id": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • O valor do campo id é inválido
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado

Administração - Categorias Eliminar

Apenas pode ser utilizado caso a categoria ainda não tenha sido utilizado em nenhum artigo.

Request POST /administration/categories/:id/delete
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Este registo não pode ser eliminado

Administração - Categorias Procurar

Permite procurar por categorias.

value mixed required

Valor a procurar

Request POST /administration/categories/find
{
    "value": ..,
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "category_id": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Categorias Lista

Devolve a lista de categorias.

active mixed

Define que estados de categorias deve retornar. Deve ser enviado um dos seguintes valores: true, false, All.

Request POST /administration/categories/list
{
    "active": ..
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "category_id": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,   
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Colaboradores Criar

name string required

Nome

country string

País

address string

Morada

city string

Localidade

postal_code string

Código postal

telephone string

Telefone

mobile string

Telemóvel

bank_number string

IBAN

is_salesman boolean

Vendedor

active boolean

Estado

Request POST /administration/employees/create
{
    "name": ..,
    "country": ..,
    "address": ..,
    "city": ..,
    "postal_code": ..,
    "email": ..,
    "telephone": ..,
    "mobile": ..,
    "bank_number": ..,
    "is_salesman": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "name": ..,
        "country": ..,
        "address": ..,
        "city": ..,
        "postal_code": ..,
        "email": ..,
        "telephone": ..,
        "mobile": ..,
        "bank_number": ..,
        "is_salesman": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado

Administração - Colaboradores Actualizar

name string required

Nome

country string

País

address string

Morada

city string

Localidade

postal_code string

Código postal

telephone string

Telefone

mobile string

Telemóvel

bank_number string

IBAN

is_salesman boolean

Vendedor

active boolean

Estado

Request POST /administration/employees/:id/update
{
    "name": ..,
    "country": ..,
    "address": ..,
    "city": ..,
    "postal_code": ..,
    "email": ..,
    "telephone": ..,
    "mobile": ..,
    "bank_number": ..,
    "is_salesman": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "name": ..,
        "country": ..,
        "address": ..,
        "city": ..,
        "postal_code": ..,
        "email": ..,
        "telephone": ..,
        "mobile": ..,
        "bank_number": ..,
        "is_salesman": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • O valor do campo id é inválido
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado

Administração - Colaboradores Eliminar

Apenas pode ser utilizado caso o colaborador ainda não tenha sido utilizado em nenhum documento / cliente.

Request POST /administration/employees/:id/delete
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Este registo não pode ser eliminado

Administração - Colaboradores Procurar

Permite procurar por colaboradores.

value mixed required

Valor a procurar

Request POST /administration/employees/find
{
    "value": ..,
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "name": ..,
            "country": ..,
            "address": ..,
            "city": ..,
            "postal_code": ..,
            "email": ..,
            "telephone": ..,
            "mobile": ..,
            "bank_number": ..,
            "is_salesman": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Colaboradores Lista

Devolve a lista de colaboradores.

active mixed

Define que estados de colaboradores deve retornar. Deve ser enviado um dos seguintes valores: true, false, All.

Request POST /administration/employees/list
{
    "active": ..
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "name": ..,
            "country": ..,
            "address": ..,
            "city": ..,
            "postal_code": ..,
            "email": ..,
            "telephone": ..,
            "mobile": ..,
            "bank_number": ..,
            "is_salesman": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": .., 
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Condições de Pagamento Criar

description string required

Descrição

description_english string

Descrição em inglês

days integer

Nº de dias

active boolean

Estado

Request POST /administration/paymentconditions/create
{
    "description": ..,
    "description_english": ..,
    "days": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "description_english": ..,
        "days": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado

Administração - Condições de Pagamento Actualizar

description string required

Descrição

description_english string

Descrição em inglês

days integer

Nº de dias

active boolean

Estado

Request POST /administration/paymentconditions/:id/update
{
    "description": ..,
    "description_english": ..,
    "days": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "description_english": ..,
        "days": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • O valor do campo id é inválido
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado

Administração - Condições de Pagamento Eliminar

Apenas pode ser utilizado caso a condição de pagamento ainda não tenha sido utilizado em nenhum documento / cliente.

Request POST /administration/paymentconditions/:id/delete
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Este registo não pode ser eliminado

Administração - Condições de Pagamento Procurar

Permite procurar por formas de pagamento.

value mixed required

Valor a procurar

Request POST /administration/paymentconditions/find
{
    "value": ..,
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "description_english": ..,
            "days": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Condições de Pagamento Lista

Devolve a lista de formas de pagamento.

active mixed

Define que estados de formas de pagamento deve retornar. Deve ser enviado um dos seguintes valores: true, false, All.

Request POST /administration/paymentconditions/list
{
    "active": ..
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "description_english": ..,
            "days": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,   
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Formas de Pagamento Criar

description string required

Descrição

description_english string

Descrição em inglês

active boolean

Estado

Request POST /administration/paymentmethods/create
{
    "description": ..,
    "description_english": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "description_english": ..,
        "saft_initials": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado

Administração - Formas de Pagamento Actualizar

description string required

Descrição

description_english string

Descrição em inglês

active boolean

Estado

Request POST /administration/paymentmethods/:id/update
{
    "description": ..,
    "description_english": ..,
    "saft_initials": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "description_english": ..,
        "saft_initials": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • O valor do campo id é inválido
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado

Administração - Formas de Pagamento Eliminar

Apenas pode ser utilizado caso a forma de pagamento ainda não tenha sido utilizado em nenhum documento / cliente.

Request POST /administration/paymentmethods/:id/delete
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Este registo não pode ser eliminado

Administração - Formas de Pagamento Procurar

Permite procurar por formas de pagamento.

value mixed required

Valor a procurar

Request POST /administration/paymentmethods/find
{
    "value": ..,
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "description_english": ..,
            "saft_initials": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Formas de Pagamento Lista

Devolve a lista de formas de pagamento.

active mixed

Define que estados de formas de pagamento deve retornar. Deve ser enviado um dos seguintes valores: true, false, All.

Request POST /administration/paymentmethods/list
{
    "active": ..
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "description_english": ..,
            "saft_initials": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,   
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Modos de Expedição Criar

description string required

Descrição

description_english string

Descrição em inglês

active boolean

Estado

Request POST /administration/shippingmodes/create
{
    "description": ..,
    "description_english": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "description_english": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado

Administração - Modos de Expedição Actualizar

description string required

Descrição

description_english string

Descrição em inglês

active boolean

Estado

Request POST /administration/shippingmodes/:id/update
{
    "description": ..,
    "description_english": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "description_english": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • O valor do campo id é inválido
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado

Administração - Modos de Expedição Eliminar

Apenas pode ser utilizado caso o modo de expedição ainda não tenha sido utilizado em nenhum documento.

Request POST /administration/shippingmodes/:id/delete
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Este registo não pode ser eliminado

Administração - Modos de Expedição Procurar

Permite procurar por modos de expedição.

value mixed required

Valor a procurar

Request POST /administration/shippingmodes/find
{
    "value": ..,
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "description_english": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Modos de Expedição Lista

Devolve a lista de modos de expedição.

active mixed

Define que estados de modos de expedição deve retornar. Deve ser enviado um dos seguintes valores: true, false, All.

Request POST /administration/shippingmodes/list
{
    "active": ..
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "description_english": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,   
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Moedas Criar

description string required

Descrição

symbol string required

Símbolo

code_iso string required

Código ISO

exchange_sale double required

Câmbio de venda

is_default boolean

Pré-definido

active boolean

Estado

Request POST /administration/currencies/create
{
    "description": ..,
    "symbol": ..,
    "code_iso": ..,
    "exchange_sale": ..,
    "is_default": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "symbol": ..,
        "code_iso": ..,
        "exchange_sale": ..,
        "is_default": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado
  • O valor indicado para o campo símbolo já se encontra registado
  • O valor indicado para o campo código iso já se encontra registado

Administração - Moedas Actualizar

description string required

Descrição

symbol string required

Símbolo

code_iso string required

Código ISO

exchange_sale double required

Câmbio de venda

is_default boolean

Pré-definido

active boolean

Estado

Request POST /administration/currencies/:id/update
{
    "description": ..,
    "symbol": ..,
    "code_iso": ..,
    "exchange_sale": ..,
    "is_default": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "symbol": ..,
        "code_iso": ..,
        "exchange_sale": ..,
        "is_default": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • O valor do campo id é inválido
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado
  • O valor indicado para o campo símbolo já se encontra registado
  • O valor indicado para o campo código ISO já se encontra registado

Administração - Moedas Eliminar

Apenas pode ser utilizado caso a moeda ainda não tenha sido utilizada em nenhum documento / cliente.

Request POST /administration/currencies/:id/delete
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Este registo não pode ser eliminado

Administração - Moedas Procurar

Permite procurar por moedas.

value mixed required

Valor a procurar

Request POST /administration/currencies/find
{
    "value": ..,
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "symbol": ..,
            "code_iso": ..,
            "exchange_sale": ..,
            "is_default": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Moedas Lista

Devolve a lista de moedas.

active mixed

Define que estados de moedas deve retornar. Deve ser enviado um dos seguintes valores: true, false, All.

Request POST /administration/currencies/list
{
    "active": ..
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "symbol": ..,
            "code_iso": ..,
            "exchange_sale": ..,
            "is_default": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Preços Criar

description string required

Descrição

is_default boolean

Pré-definido

active boolean

Estado

Request POST /administration/prices/create
{
    "description": ..,
    "is_default": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "is_default": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado

Administração - Preços Actualizar

description string required

Descrição

is_default boolean

Pré-definido

active boolean

Estado

Request POST /administration/prices/:id/update
{
    "description": ..,
    "is_default": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "is_default": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • O valor do campo id é inválido
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado

Administração - Preços Eliminar

Apenas pode ser utilizado caso o preço ainda não tenha sido utilizado em nenhum documento / artigo.

Request POST /administration/prices/:id/delete
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Este registo não pode ser eliminado

Administração - Preços Procurar

Permite procurar por preços.

value mixed required

Valor a procurar

Request POST /administration/prices/find
{
    "value": ..,
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "is_default": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Preços Lista

Devolve a lista de preços.

active mixed

Define que estados de preços deve retornar. Deve ser enviado um dos seguintes valores: true, false, All.

Request POST /administration/prices/list
{
    "active": ..
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "is_default": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,   
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Séries Criar

description string required

Descrição

valid_until integer required

Válido até. Preencher apenas com o ano.

assign_to_all boolean

Determina se deve atribuir de imediato a série a todos os tipos de documento

assign_as_default boolean

Determina se deve colocar a série como pré-definida

communicate boolean

Determina se deve comunicar a série à AT. Necessário que a configuração do utilizador de acesso aos serviços AT esteja correctamente configurado.

communicate_documents_types json array

Determina quais os tipos de documentos a comunicar à AT com a respectiva série. Só necessário preencher caso o parâmetro communicate seja true.

active boolean

Estado

Request POST /administration/series/create
{
    "description": ..,
    "valid_until": ..,
    "assign_to_all": ..,
    "assign_as_default": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "valid_until": ..,
        "type": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado
  • A descrição da série é inválida. Não são permitidos: acentos, espaços, caracteres especiais (excepto: . _ -)

Administração - Séries Actualizar

description string required

Descrição

valid_until integer required

Válido até. Preencher apenas com o ano.

active boolean

Estado

Request POST /administration/series/:id/update
{
    "description": ..,
    "valid_until": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "valid_until": ..,
        "type": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • O valor do campo id é inválido
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado
  • A descrição da série é inválida. Não são permitidos: acentos, espaços, caracteres especiais (excepto: . _ -)

Administração - Séries Eliminar

Apenas pode ser utilizado caso a série ainda não tenha sido utilizado em nenhum documento.

Request POST /administration/series/:id/delete
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Este registo não pode ser eliminado

Administração - Séries Comunicar série

Permite comunicar uma série à Autoridade Tributária para todos os tipos de documento em que esta esteja atribuída.

Request POST /administration/series/:id/communicate
Sem parâmetros
Response 200
{
    "status": true,
}
Possíveis erros
  • O valor do campo id é inválido
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • A série não se encontra activa
  • A série encontra-se expirada
  • Configure primeiro o utilizador de acesso de webservice AT
  • Todos os tipos de documento já se encontram comunicados!
  • Não foi possível comunicar a série no tipo de documento ..., erro: ...

Administração - Séries Procurar

Permite procurar por série.

value mixed required

Valor a procurar

Request POST /administration/series/find
{
    "value": ..,
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "valid_until": ..,
            "type": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Séries Lista

Devolve a lista de séries.

active mixed

Define que estados de séries deve retornar. Deve ser enviado um dos seguintes valores: true, false, All.

Request POST /administration/series/list
{
    "active": ..
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "valid_until": ..,
            "type": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,   
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Séries Por tipo de documento

Devolve a lista de séries por tipo de documento.

document_type_id mixed required

ID da tabela tipos de documento

Request POST /administration/series/by_document_type
{
    "document_type_id": ..
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "valid_until": ..,
            "type": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,   
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Taxas de IVA Criar

description string required

Descrição

tax double required

Taxa %

type string required

Tipo de taxa. Deve ser enviado um dos seguintes valores: Normal, Intermédia, Isenta, Reduzida.

saft_region string required

Região do SAF-T. Deve ser enviado um dos seguintes valores: PT, PT-AC, PT-MA. Também pode ser enviado um valor de acordo a norma ISO 3166, nomeadamente Alpha-2 Code.

active boolean

Estado

Request POST /administration/vatrates/create
{
    "description": ..,
    "tax": ..,
    "type": ..,
    "saft_region": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "tax": ..,
        "type": ..,
        "saft_region": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": .., 
    }
}
Possíveis erros
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado
  • O valor indicado para o campo taxa já se encontra registado

Administração - Taxas de IVA Actualizar

description string required

Descrição

tax double required

Taxa %

type string required

Tipo de taxa. Deve ser enviado um dos seguintes valores: Normal, Intermédia, Isenta, Reduzida.

saft_region string required

Região do SAF-T. Deve ser enviado um dos seguintes valores: PT, PT-AC, PT-MA. Também pode ser enviado um valor de acordo a norma ISO 3166, nomeadamente Alpha-2 Code.

active boolean

Estado

Request POST /administration/vatrates/:id/update
{
    "description": ..,
    "tax": ..,
    "type": ..,
    "saft_region": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "tax": ..,
        "type": ..,
        "saft_region": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": .., 
    }
}
Possíveis erros
  • O valor do campo id é inválido
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado
  • O valor indicado para o campo taxa já se encontra registado

Administração - Taxas de IVA Eliminar

Apenas pode ser utilizado caso a Taxa de IVA ainda não tenha sido utilizado em nenhum documento / artigo.

Request POST /administration/vatrates/:id/delete
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Este registo não pode ser eliminado

Administração - Taxas de IVA Procurar

Permite procurar por Taxas de IVA.

value mixed required

Valor a procurar

Request POST /administration/vatrates/find
{
    "value": ..,
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "tax": ..,
            "type": ..,
            "saft_region": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": .., 
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Taxas de IVA Lista

Devolve a lista de Taxas de IVA.

active mixed

Define que estados de Taxas de IVA deve retornar. Deve ser enviado um dos seguintes valores: true, false, All.

Request POST /administration/vatrates/list
{
    "active": ..
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "tax": ..,
            "type": ..,
            "saft_region": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": .., 
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Tipos de Documento Actualizar

print_report string required

Formato de papel. Deve ser enviado um dos seguintes valores: A4, POS.

print_report_width integer

Largura do papel. Apenas obrigatório caso o valor do campo print_report seja POS. Tamanho em milímetros.

print_pages_number integer

Nº de vias a imprimir. Apenas obrigatório caso o valor do campo print_report seja A4.

print_margin_top integer

Margem superior

print_margin_bottom integer

Margem inferior

print_margin_right integer

Margem direita

print_margin_left integer

Margem esquerda

print_automatic boolean

Define se deve emitir de imediato o PDF após terminar o documento

sign_document_automatic boolean

Define se deve assinar digitalmente o PDF após terminar o documento

send_email_automatic boolean

Define se envia automaticamente um email (com o anexo do PDF emitido) ao cliente após terminar o documento

send_sms_automatic boolean

Define se envia automaticamente uam SMS ao cliente após terminar o documento

stock_check_negative boolean

Define se é possível terminar o documento caso o stock do artigo seja negativo

stock_check_minimum boolean

Define se deve alertar o utilizador caso o stock do artigo ultrapasse o stock mínimo definido

series json array

Lista de séries que constam no tipo de documento

id integer required

ID da série

number integer required

Nº documento (deve-se iniciar no 1)

is_default boolean

Pré-definido

active boolean

Estado

active boolean

Estado

Request POST /administration/documentstypes/:id/update
{
    "print_report": ..,
    "print_width": ..,
    "print_pages_number": ..,
    "print_margin_top": ..,
    "print_margin_bottom": ..,
    "print_margin_right": ..,
    "print_margin_left": ..,
    "print_automatic": ..,
    "sign_document_automatic": ..,
    "send_email_automatic": ..,
    "send_sms_automatic": ..,
    "stock_check_negative": ..,
    "stock_check_minimum": ..,
    "series": [],    
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "saft_initials": ..,
        "type": ..,
        "print_report": ..,
        "print_report_width": ..,
        "print_pages_number": ..,
        "print_margin_top": ..,        
        "print_margin_bottom": ..,
        "print_margin_right": ..,
        "print_margin_left": ..,
        "print_automatic": ..,
        "sign_document_automatic": ..,
        "send_email_automatic": ..,
        "send_sms_automatic": ..,
        "stock_check_negative": ..,
        "stock_check_minimum": ..,        
        "active": ..,
        "documentstypesseries": []
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • O valor do campo id é inválido
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado

Administração - Tipos de Documento Comunicar série

Permite comunicar uma série, por tipo de documento, à Autoridade Tributária.

Request POST /administration/documentstypes/:id/:serie_id/communicate
Sem parâmetros
Response 200
{
    "status": true,
    "atcud": ..
}
Possíveis erros
  • O valor do campo id é inválido
  • O valor do campo serie_id é inválido
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • Já existe um ATCUD atribuído para este tipo de documento & série
  • Configure primeiro o utilizador de acesso de webservice AT
  • A série não se encontra activa no tipo de documento
  • A série encontra-se expirada
  • Não foi possível comunicar a série, erro: ..

Administração - Tipos de Documento Procurar

Permite procurar por tipos de documento.

value mixed required

Valor a procurar

Request POST /administration/documentstypes/find
{
    "value": ..,
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "saft_initials": ..,
            "type": ..,
            "print_report": ..,
            "print_report_width": ..,
            "print_pages_number": ..,
            "print_margin_top": ..,        
            "print_margin_bottom": ..,
            "print_margin_right": ..,
            "print_margin_left": ..,
            "print_automatic": ..,
            "sign_document_automatic": ..,
            "send_email_automatic": ..,
            "send_sms_automatic": ..,
            "stock_check_negative": ..,
            "stock_check_minimum": ..,            
            "active": ..,
            "documentstypesseries": []
            "updated_at": ..,
            "created_at": ..,
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Tipos de Documento Lista

Devolve a lista de tipos de documento.

active mixed

Define que estados de tipos de documento deve retornar. Deve ser enviado um dos seguintes valores: true, false, All.

Request POST /administration/documentstypes/list
{
    "active": ..
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "saft_initials": ..,
            "type": ..,
            "print_report": ..,
            "print_report_width": ..,
            "print_pages_number": ..,
            "print_margin_top": ..,        
            "print_margin_bottom": ..,
            "print_margin_right": ..,
            "print_margin_left": ..,            
            "print_automatic": ..,
            "sign_document_automatic": ..,
            "send_email_automatic": ..,
            "send_sms_automatic": ..,
            "stock_check_negative": ..,
            "stock_check_minimum": ..,            
            "active": ..,
            "documentstypesseries": []
            "updated_at": ..,
            "created_at": ..,
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Veículos Criar

name string required

Nome

license_plate string required

Matrícula

active boolean

Estado

Request POST /administration/vehicles/create
{
    "name": ..,
    "license_plate": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "name": ..,
        "license_plate": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo nome já se encontra registado
  • O valor indicado para o campo matrícula já se encontra registado

Administração - Veículos Actualizar

name string required

Nome

license_plate string required

Matrícula

active boolean

Estado

Request POST /administration/vehicles/:id/update
{
    "name": ..,
    "license_plate": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "name": ..,
        "license_plate": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • O valor do campo id é inválido
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo nome já se encontra registado
  • O valor indicado para o campo matrícula já se encontra registado

Administração - Veículos Eliminar

Apenas pode ser utilizado caso o veículo ainda não tenha sido utilizado em nenhum documento.

Request POST /administration/vehicles/:id/delete
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Este registo não pode ser eliminado

Administração - Veículos Procurar

Permite procurar por veículos.

value mixed required

Valor a procurar

Request POST /administration/vehicles/find
{
    "value": ..,
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "name": ..,
            "license_plate": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Veículos Lista

Devolve a lista de veículos.

active mixed

Define que estados de veículos deve retornar. Deve ser enviado um dos seguintes valores: true, false, All.

Request POST /administration/vehicles/list
{
    "active": ..
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "name": ..,
            "license_plate": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Unidades Criar

description string required

Descrição

symbol string required

Símbolo

active boolean

Estado

Request POST /administration/units/create
{
    "description": ..,
    "symbol": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "symbol": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado
  • O valor indicado para o campo símbolo já se encontra registado

Administração - Unidades Actualizar

description string required

Descrição

symbol string required

Símbolo

active boolean

Estado

Request POST /administration/units/:id/update
{
    "description": ..,
    "symbol": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "description": ..,
        "symbol": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • O valor do campo id é inválido
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo descrição já se encontra registado
  • O valor indicado para o campo símbolo já se encontra registado

Administração - Unidades Eliminar

Apenas pode ser utilizado caso a unidade ainda não tenha sido utilizada em nenhum documento / artigo.

Request POST /administration/units/:id/delete
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Este registo não pode ser eliminado

Administração - Unidades Procurar

Permite procurar por unidades.

value mixed required

Valor a procurar

Request POST /administration/units/find
{
    "value": ..,
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "symbol": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Administração - Unidades Lista

Devolve a lista de unidades.

active mixed

Define que estados de unidades deve retornar. Deve ser enviado um dos seguintes valores: true, false, All.

Request POST /administration/units/list
{
    "active": ..
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "description": ..,
            "symbol": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Subscrição

Este endpoint visa gerir todas as tabelas de subscrição.

Subscrição - Locais Criar

name string required

Nome

address string required

Morada

city string required

Localidade

postal_code string required

Código postal

country string required

País

telephone string

Telefone

type string required

Tipo de local. Preencher com Interno ou Externo.

document_type string required

Tipo de documento. Pode ser enviado o ID ou o descritivo, exemplo: Factura, Factura Recibo, Factura Simplificada, Nota de crédito ou Nota de débito

vat_type string required

Tipo de IVA. Deve ser enviado um dos seguintes valores: Debitar IVA, IVA incluído, Não fazer nada.

warehouse string

Armazém. Pode ser enviado o ID ou o descritivo.

active boolean

Estado

Request POST /subscription/locations/create
{
    "name": ..,
    "address": ..,
    "city": ..,
    "postal_code": ..,
    "country": ..,
    "telephone": ..,
    "type": ..,
    "document_type": ..,
    "vat_type": ..,
    "warehouse": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "name": ..,
        "address": ..,
        "city": ..,
        "postal_code": ..,
        "country": ..,
        "telephone": ..,
        "type": ..,
        "document_type": ..,
        "vat_type": ..,
        "warehouse": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo nome já se encontra registado
  • Atingiu o limite de locais internos para o plano actual
  • O valor do campo type é inválido
  • O valor do campo document_type é inválido
  • O valor do campo vat_type é inválido
  • O valor do campo warehouse é inválido

Subscrição - Locais Actualizar

name string required

Nome

address string required

Morada

city string required

Localidade

postal_code string required

Código postal

country string required

País

telephone string

Telefone

type string required

Tipo de local. Preencher com Interno ou Externo.

document_type string required

Tipo de documento. Pode ser enviado o ID ou o descritivo, exemplo: Factura, Factura Recibo, Factura Simplificada, Nota de crédito ou Nota de débito

vat_type string required

Tipo de IVA. Deve ser enviado um dos seguintes valores: Debitar IVA, IVA incluído, Não fazer nada.

warehouse string

Armazém. Pode ser enviado o ID ou o descritivo.

active boolean

Estado

Request POST /subscription/locations/:id/update
{
    "name": ..,
    "address": ..,
    "city": ..,
    "postal_code": ..,
    "country": ..,
    "telephone": ..,
    "type": ..,
    "document_type": ..,
    "vat_type": ..,
    "warehouse": ..,
    "active": ..,
    "active": ..,
}
Response 200
{
    "status": true,
    "data": 
    {
        "id": ..,
        "name": ..,
        "address": ..,
        "city": ..,
        "postal_code": ..,
        "country": ..,
        "telephone": ..,
        "type": ..,
        "document_type": ..,
        "vat_type": ..,
        "warehouse": ..,
        "active": ..,
        "updated_at": ..,
        "created_at": ..,
    }
}
Possíveis erros
  • O valor do campo id é inválido
  • Não preencheu todos os campos obrigatórios
  • Não tem permissões para executar esta operação
  • É obrigatória a indicação de um valor para o campo X
  • O valor indicado para o campo nome já se encontra registado
  • Atingiu o limite de locais internos para o plano actual
  • O valor do campo type é inválido
  • O valor do campo document_type é inválido
  • O valor do campo vat_type é inválido
  • O valor do campo warehouse é inválido

Subscrição - Locais Eliminar

Apenas pode ser utilizado caso o local ainda não tenha sido utilizado em nenhuma venda / recibo.

Request POST /subscription/locations/:id/delete
Sem parâmetros
Response 200
{
    "status": true
}
Possíveis erros
  • O valor do campo id é inválido
  • Não tem permissões para executar esta operação
  • Este registo não pode ser eliminado

Subscrição - Locais Procurar

Permite procurar por locais.

value mixed required

Valor a procurar

Request POST /subscription/locations/find
{
    "value": ..,
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "name": ..,
            "address": ..,
            "city": ..,
            "postal_code": ..,
            "country": ..,
            "telephone": ..,
            "type": ..,
            "document_type": ..,
            "vat_type": ..,
            "warehouse": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação

Subscrição - Locais Lista

Devolve a lista de locais.

active mixed

Define que estados de locais deve retornar. Deve ser enviado um dos seguintes valores: true, false, All.

Request POST /subscription/locations/list
{
    "active": ..
}
Response 200
{
    "status": true,
    "data": 
    [
        {
            "id": ..,
            "name": ..,
            "address": ..,
            "city": ..,
            "postal_code": ..,
            "country": ..,
            "telephone": ..,
            "type": ..,
            "document_type": ..,
            "vat_type": ..,
            "warehouse": ..,
            "active": ..,
            "updated_at": ..,
            "created_at": ..,
        }
    ]
}
Possíveis erros
  • Não tem permissões para executar esta operação