API - Documentação

Tudo o que precisa para incorporar o seu serviço com o nosso!

Início

Bem vindo à nossa API. Aqui vai encontrar tudo o que precisa para integrar a sua aplicação com o nosso Software de Facturação.

Antes de começar, deve:

  1. Escolher um dos planos
  2. Adquirir a sua API

Após ter acesso às suas credênciais, deve configurar alguns campos obrigatórios para bom funcionamento da comunicação de ambas as partes, como por exemplo a série e o local.


Autenticação

A autenticação na nossa API é composta por dois valores: key e secret que devem ser enviados no header do pedido.

No cabeçalho do pedido deve constatar Authorization: Basic, cujo valor é a junção dos dois valores previamente mencionados em formato BASE64.

É ainda necessário que em todos os pedidos realizados seja mencionado o Content-type: application/json.


Exemplo de pedido

Independentemente da linguagem de programação em uso, o pedido deve ser feito tendo por base a seguinte estrutura:

curl --request POST
--url 'https://facturalusa.pt/api/{URL}'
--header 'Accept: application/json'
--header 'Content-type: application/json'
--header 'Authorization: Basic BASE64(app_key ':' app_value)'
--body '{"param1": "value1"}'

Deverá ser sempre interpretado o código HTTP da resposta de forma a diferenciar o erro do sucesso.

Erros e respostas

Quando os pedidos são executados sem qualquer anomalia, será sempre retornado o código 200.

Código Texto Descrição
200 OK Pedido executado com sucesso!
204 NO CONTENT Não foram enviados nenhuns parâmetros
401 UNAUTHORIZED Os valores fornecidos na autenticação são inválidos
403 FORBIDDEN O formato enviado no cabeçalho é inválido
405 METHOD NOT ALLOWED O método enviado no cabeçalho é inválido
422 SOME PARAMETERS ARE INCORRECT Um ou mais parâmetros enviados são inválidos

Lista de possíveis mensagens de erro

Documentos > Criar

  • Campo tipo de documento (FT, FS, FR, FP, NC, ND, EC, OC, ou RC) em falta
  • Estrutura de cliente em falta
  • Estrutura de artigos em falta
  • Estrutura de linhas em falta
  • Não existe nenhuma série configurada para trabalhar com a API
  • O tipo de documento seleccionado não contém a série da API atribuído
  • Não existe nenhum local configurado para trabalhar com a API
  • O id do cliente não existe, tem de o criar primeiro
  • O contribuinte aparenta ser inválido
  • O modo de expedição não existe
  • A taxa de IVA da despesa de transporte não existe
  • O valor da despesa de transporte tem um formato de preço inválido
  • Os campos referência, preço e quantidade dos artigos são obrigatórios
  • O artigo com a referência: x tem um formato de preço inválido
  • O artigo com a referência: x tem um formato de quantidade inválido
  • O artigo com a referência: x não existe
  • Os campos id e tipo de documento nas linhas são obrigatórios
  • O documento com o id: x não existe
  • Não existe saldo em aberto no documento com o id: x
  • As linhas associadas ao recibo tem de pertencer todas ao mesmo cliente

Documentos > Gerar PDF

  • Campo tipo de documento (FT, FS, FR, FP, NC, ND, EC, OC, ou RC) em falta
  • Campos obrigatórios em falta
  • Documento não encontrado
  • É obrigatório justificar a visualização do PDF

Documentos > Email

  • Campo tipo de documento (FT, FS, FR, FP, NC, ND, EC, OC, ou RC) em falta
  • Campos obrigatórios em falta
  • Email inválido
  • Documento não encontrado ou precisa de gerar o PDF 1º

Clientes > Criar

  • Os campos código e nome são de preenchimento obrigatório
  • O código introduzido já existe
  • O contribuinte introduzido já existe
  • O contribuinte introduzido é inválido para Portugal
  • Não existe nenhum local configurado para trabalhar com a API
  • O país introduzido é inválido

Clientes > Actualizar

  • Os campos id, código e nome são de preenchimento obrigatório
  • O id introduzido não existe
  • O código introduzido já existe
  • O contribuinte introduzido já existe
  • O contribuinte introduzido é inválido para Portugal
  • Não existe nenhum local configurado para trabalhar com a API
  • Não existe nenhum local configurado para trabalhar com a API
  • O nome do cliente encontra-se bloqueado, não é possível alterar
  • O código do cliente encontra-se bloqueado, não é possível alterar
  • O contribuinte do cliente encontra-se bloqueado, não é possível alterar

Clientes > Procurar

  • Os campos valor e tipo são de preenchimento obrigatório
  • O campo tipo deve conter um dos valores: id, codigo ou contribuinte
  • Nenhum cliente encontrado

Artigos > Stock

  • Os campos valor e tipo são de preenchimento obrigatório
  • O campo tipo deve conter um dos valores: id, referencia ou descricao
  • O artigo não existe, não está activo ou não é um tipo de artigo mercadoria
  • Não existe nenhum local configurado para trabalhar com a API

Formas de pagamento

No processo de criação de um documento, pode identificar qual a forma de pagamento que o cliente seleccionou.

Código Descrição
CC Cartão de crédito
CD Cartão de débito
CH Cheque bancário
CO Cheque ou cartão oferta
CS Compensação de saldos em conta corrente
DE Dinheiro electrónico
LC Letra comercial
MB Referências de pagamento para Multibanco
NU Numerário
OU Outros meios
PR Permuta de bens
TB Transferência bancária ou débito directo autorizado
TR Ticket restaurante


Lista de países

Lista de países aceites para quando há a criação de uma conta de cliente.

  • Aaland Islands
  • Afghanistan
  • Albania
  • Algeria
  • American Samoa
  • Andorra
  • Angola
  • Anguilla
  • Antarctica
  • Antigua and Barbuda
  • Argentina
  • Armenia
  • Aruba
  • Ascension Island (British)
  • Australia
  • Austria
  • Azerbaijan
  • Bahamas
  • Bahrain
  • Bangladesh
  • Barbados
  • Belarus
  • Belgium
  • Belize
  • Benin
  • Bermuda
  • Bhutan
  • Bolivia
  • Bonaire, Sint Eustatius and Saba
  • Bosnia and Herzegovina
  • Botswana
  • Bouvet Island
  • Brazil
  • British Indian Ocean Territory
  • Brunei Darussalam
  • Bulgaria
  • Burkina Faso
  • Burundi
  • Cambodia
  • Cameroon
  • Canada
  • Canary Islands
  • Cape Verde
  • Cayman Islands
  • Central African Republic
  • Chad
  • Chile
  • China
  • Christmas Island
  • Cocos (Keeling) Islands
  • Colombia
  • Comoros
  • Congo
  • Cook Islands
  • Costa Rica
  • Cote D'Ivoire
  • Croatia
  • Cuba
  • Curacao
  • Cyprus
  • Czech Republic
  • Democratic Republic of Congo
  • Denmark
  • Djibouti
  • Dominica
  • Dominican Republic
  • East Timor
  • Ecuador
  • Egypt
  • El Salvador
  • Equatorial Guinea
  • Eritrea
  • Estonia
  • Ethiopia
  • FYROM
  • Falkland Islands (Malvinas)
  • Faroe Islands
  • Fiji
  • Finland
  • France
  • French Guiana
  • French Polynesia
  • French Southern Territories
  • Gabon
  • Gambia
  • Georgia
  • Germany
  • Ghana
  • Gibraltar
  • Greece
  • Greenland
  • Grenada
  • Guadeloupe
  • Guam
  • Guatemala
  • Guernsey
  • Guinea
  • Guinea-Bissau
  • Guyana
  • Haiti
  • Heard and Mc Donald Islands
  • Honduras
  • Hong Kong
  • Hungary
  • Iceland
  • India
  • Indonesia
  • Iran (Islamic Republic of)
  • Iraq
  • Ireland
  • Isle of Man
  • Israel
  • Italy
  • Jamaica
  • Japan
  • Jersey
  • Jordan
  • Kazakhstan
  • Kenya
  • Kiribati
  • Korea, Republic of
  • Kosovo, Republic of
  • Kuwait
  • Kyrgyzstan
  • Lao People's Democratic Republic
  • Latvia
  • Lebanon
  • Lesotho
  • Liberia
  • Libyan Arab Jamahiriya
  • Liechtenstein
  • Lithuania
  • Luxembourg
  • Macau
  • Madagascar
  • Malawi
  • Malaysia
  • Maldives
  • Mali
  • Malta
  • Marshall Islands
  • Martinique
  • Mauritania
  • Mauritius
  • Mayotte
  • Mexico
  • Micronesia, Federated States of
  • Moldova, Republic of
  • Monaco
  • Mongolia
  • Montenegro
  • Montserrat
  • Morocco
  • Mozambique
  • Myanmar
  • Namibia
  • Nauru
  • Nepal
  • Netherlands
  • Netherlands Antilles
  • New Caledonia
  • New Zealand
  • Nicaragua
  • Niger
  • Nigeria
  • Niue
  • Norfolk Island
  • North Korea
  • Northern Mariana Islands
  • Norway
  • Oman
  • Pakistan
  • Palau
  • Palestinian Territory, Occupied
  • Panama
  • Papua New Guinea
  • Paraguay
  • Peru
  • Philippines
  • Pitcairn
  • Poland
  • Portugal
  • Puerto Rico
  • Qatar
  • Reunion
  • Romania
  • Russian Federation
  • Rwanda
  • Saint Kitts and Nevis
  • Saint Lucia
  • Saint Vincent and the Grenadines
  • Samoa
  • San Marino
  • Sao Tome and Principe
  • Saudi Arabia
  • Senegal
  • Serbia
  • Seychelles
  • Sierra Leone
  • Singapore
  • Slovak Republic
  • Slovenia
  • Solomon Islands
  • Somalia
  • South Africa
  • South Georgia & South Sandwich Islands
  • South Sudan
  • Spain
  • Sri Lanka
  • St. Barthelemy
  • St. Helena
  • St. Martin (French part)
  • St. Pierre and Miquelon
  • Sudan
  • Suriname
  • Svalbard and Jan Mayen Islands
  • Swaziland
  • Sweden
  • Switzerland
  • Syrian Arab Republic
  • Taiwan
  • Tajikistan
  • Tanzania, United Republic of
  • Thailand
  • Togo
  • Tokelau
  • Tonga
  • Trinidad and Tobago
  • Tristan da Cunha
  • Tunisia
  • Turkey
  • Turkmenistan
  • Turks and Caicos Islands
  • Tuvalu
  • Uganda
  • Ukraine
  • United Arab Emirates
  • United Kingdom
  • United States
  • United States Minor Outlying Islands
  • Uruguay
  • Uzbekistan
  • Vanuatu
  • Vatican City State (Holy See)
  • Venezuela
  • Viet Nam
  • Virgin Islands (British)
  • Virgin Islands (U.S.)
  • Wallis and Futuna Islands
  • Western Sahara
  • Yemen
  • Zambia
  • Zimbabwe

Plugins de Integração

Consoante as necessidades, os plugins vão sendo adicionados nesta lista para que seja mais fácil a integração entre a sua loja online e o nosso software de facturação.

Opencart

Versão 3.x
Download

Criar documento

Cria um novo documento do tipo Factura, Factura recibo, Factura simplificada, Nota crédito, Nota débito, Factura pró-forma, Orçamento, Encomenda ou Recibo.

NOTAS

  1. O cliente e os artigos já devem existir na base de dados. Utilize as funcionalidades do cliente para criar o mesmo antes de criar o documento.
  2. O campo morada_entrega serve para determinar se a morada de entrega é diferente da morada de facturação. É necessário que a morada de entrega já exista na ficha do cliente.
  3. O campo gerar_pdf serve para forçar a pré-visualização do documento PDF. Nem sempre o documento é pré-visualizado após terminar o mesmo, pois depende das opções activas do tipo de documento.
  4. O documento é sempre criado com o estado de terminado/finalizado.
  5. Deve utilizar o cliente com o ID 1 quando não for fornecido qualquer dado fiscal por parte do cliente ou quando o cliente apenas fornecer o contribuinte como meio de identificação.
  6. Os campos desconto_final, modo_expedicao_id, despesa_transporte_taxaiva_id e despesa_transporte_valor não são obrigatórios.
  7. Para preenchimento das despesas de transporte, os campos acima mencionados são todos obrigatórios.
  8. Para preenchimento dos valores modo_expedicao_id e despesa_transporte_taxaiva_id é necessário aceder às respectivas tabelas em Login > Administração e obter o ID.
  9. O valor do campo desconto_final é unitário
  10. O valor do campo desconto nas linhas de artigos é percentual
  11. O valor do campo forma_pagamento contempla tanto o código como a descrição
  12. O valor do campo descricao_detalhada é facultativo e serve apenas de apoio ao artigo em questão (por exemplo para mencionar opções de Tamanho;Cor)

POST

https://facturalusa.pt/api/documentos/criar

Lista de parâmetros

{
   'tipo_documento': 'FT',
   'desconto_final': '0.00',
   'forma_pagamento': 'NU',
   'modo_expedicao_id': '',
   'despesa_transporte_taxaiva_id': '',
   'despesa_transporte_valor': '',
   'cliente': {'id': 1, 'contribuinte': '999999990', morada_entrega: FALSE},
   'artigos': [{'referencia': '001', 'preco': '10.00', 'quantidade': 2, 'desconto': '0.00',                 'descricao_detalhada': ''}],
   'gerar_pdf': TRUE,
   'observacoes': ''
}

Conteúdo da resposta

{
   'msg': 'Documento criado com sucesso!',
   'id': 300,
   'numero': 15,
   'tipo_documento_iniciais_saft': 'FT',
   'tipo_documento_descricao': 'Factura',
   'serie': '2018',
   'total_sem_iva': '10.00',
   'total_iva': '2.30',
   'total_geral': '12.30',
   'pdf': 'url',
   'email_enviado': TRUE/FALSE
}

Lista de parâmetros RECIBO (RC)

No caso dos recibos, apesar do url ser o mesmo, os parâmetros a enviar são diferentes, bem como a resposta é diferente.

{
   'tipo_documento': 'RC',
   'forma_pagamento': 'NU',
   'linhas': [{'id': 100, 'tipo_documento': FT}],
   'gerar_pdf': TRUE,
   'observacoes': ''
}

No caso da emissão de recibos, as linhas do recibo (que dizem respeito às Facturas e Notas de crédito/débito) devem pertencer todas ao mesmo cliente.

Conteúdo da resposta

{
   'msg': 'Documento criado com sucesso!',
   'id': 300,
   'numero': 15,
   'tipo_documento_iniciais_saft': 'RC',
   'tipo_documento_descricao': 'Recibo de Cliente',
   'serie': '2018',
   'total_saldo': '12.30',
   'total_pago': '12.30',
   'total_final': '12.30',
   'pdf': 'url',
   'email_enviado': TRUE/FALSE
}


Gerar PDF do documento

Sempre que se justifique pode gerar novamente o PDF do documento (mesmo que já tenha sido gerado) e será devolvido o url do ficheiro.

NOTAS

  1. Se o documento já tiver sido visualizado é necessário, para efeitos da Autoridade Tributária, justificar o porquê da nova visualização.
  2. Pode tirar a 2ª via ou o original, desde que justificado.

POST

https://facturalusa.pt/api/documentos/pdf

Lista de parâmetros

{
   'id': '121',
   'tipo_documento': 'FT',
   'original': FALSE,
   'motivo': ''
}

Conteúdo da resposta

{
   'msg': 'PDF gerado com sucesso!',
   'pdf': 'url'
}


Enviar documento por email

Pode usufruir dos nossos serviços para que o email seja enviado ao cliente com o documento PDF em anexo.

NOTAS

  1. O documento pode já ter sido enviado ao cliente - se a opção automática de envio estiver activada na subscrição.
  2. Na criação do documento via API é devolvido se o email foi ou não já enviado.
  3. Os campos assunto e mensagem não são de preenchimento obrigatório.

PUT

https://facturalusa.pt/api/documentos/email

Lista de parâmetros

{
   'id': '121',
   'tipo_documento': 'FT',
   'email': 'exemplo@exemplo.com',
   'assunto': '',
   'mensagem': ''
}

Conteúdo da resposta

{
   'msg': 'Email enviado com sucesso!'
}


Criar cliente

Cria um novo cliente para ser utilizado no momento da facturação.

NOTAS

  1. Apenas os campos codigo e nome são de preenchimento obrigatório.
  2. Se não for atribuído um valor ao campo do contribuinte, será assumido 999999990.

POST

https://facturalusa.pt/api/clientes/criar

Lista de parâmetros

{
   'codigo': 'J001',
   'nome': 'João Antunes',
   'contribuinte': '',
   'contacto': '',
   'email': '',
   'telefone': '',
   'telemovel': '',
   'observacoes': '',
   'morada': ['facturacao': ['pais': '', 'morada': '', 'localidade': '', 'codigo_postal': ''],
              'entrega': ['pais': '', 'morada': '', 'localidade': '', 'codigo_postal': '']]
}

Conteúdo da resposta

{
   'msg': 'Cliente criado com sucesso!',
   'id': 10
}


Actualizar cliente

Actualiza os dados existentes de um cliente.

NOTAS

  1. Os campos id, codigo e nome são de preenchimento obrigatório.
  2. Se não for atribuído um valor ao campo do contribuinte, será assumido 999999990.
  3. A alteração dos campos nome, codigo, contribuinte está sujeito a verificação de bloqueio. Será devolvida uma mensagem de erro se se justificar.

PUT

https://facturalusa.pt/api/clientes/actualizar

Lista de parâmetros

{
   'id': 10,
   'codigo': 'J001',
   'nome': 'João Antunes',
   'contribuinte': '',
   'contacto': '',
   'email': '',
   'telefone': '',
   'telemovel': '',
   'observacoes': '',
   'morada': ['facturacao': ['pais': '', 'morada': '', 'localidade': '', 'codigo_postal': ''],
              'entrega': ['pais': '', 'morada': '', 'localidade': '', 'codigo_postal': '']]
}

Conteúdo da resposta

{
   'msg': 'Cliente editado com sucesso!'
}


Procurar cliente

Devolve os dados do cliente pela pesquisa do id, código ou contribuinte.

NOTAS

  1. O campo valor aceita os formatos de inteiro e texto.
  2. O campo tipo deve conter um dos valores: id, codigo ou contribuinte.

POST

https://facturalusa.pt/api/clientes/procurar

Lista de parâmetros

{
   'valor': '',
   'tipo': ''
}

Conteúdo da resposta

{
   'msg': 'Cliente encontrado com sucesso!',
   'id': '',
   'codigo': '',
   'nome': '',
   'contribuinte': '',
   'contacto': '',
   'email': '',
   'telefone': '',
   'telemovel': '',
   'observacoes': '',
   'morada': ['facturacao': ['pais': '', 'morada': '', 'localidade': '', 'codigo_postal': ''],
              'entrega': ['pais': '', 'morada': '', 'localidade': '', 'codigo_postal': '']]
   'codigo_bloqueado': TRUE/FALSE,
   'nome_bloqueado': TRUE/FALSE,
   'contribuinte_bloqueado': TRUE/FALSE
}


Stock do artigo

Devolve a quantidade em stock de determinado artigo pelos campos id, referência ou descrição.

NOTAS

  1. O campo valor aceita os formatos de inteiro e texto.
  2. O campo tipo deve conter um dos valores: id, referencia ou descricao.
  3. A quantidade é devolvida com 5 casas decimais.
  4. O campo quantidade_disponivel representa o stock real disponível.
  5. O campo quantidade_encomendas representa o stock que está pendente para facturação nas encomendas.

POST

https://facturalusa.pt/api/artigos/stock

Lista de parâmetros

{
   'valor': '',
   'tipo': ''
}

Conteúdo da resposta

{
   'quantidade_disponivel': 10.00000,
   'quantidade_encomendas': 5.00000,
}