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:
-
Escolher um dos planos
-
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
- O país introduzido é inválido
- 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 > Criar
- Os campos referência, descrição, taxa iva, isenção iva, unidade e tipo de contabilidade são de preenchimento obrigatório
- A referência introduzida já existe
- A descrição introduzida já existe
- Existem caracteres improprios na referência
- Existem caracteres improprios na descrição
- O tipo de contabilidade introduzido não existe
- O preço de custo é inválido
- O preço de venda é inválido
Artigos > Actualizar
- Os campos id, referência, descrição, taxa iva, isenção iva, unidade e tipo de contabilidade são de preenchimento obrigatório
- O id introduzido já existe
- A referência introduzida já existe
- A descrição introduzida já existe
- Existem caracteres improprios na referência
- Existem caracteres improprios na descrição
- O tipo de contabilidade introduzido não existe
- O preço de custo é inválido
- O preço de venda é inválido
- A referência encontra-se bloqueada, não é possível alterar
- A descrição encontra-se bloqueada, não é possível alterar
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 |
Tipos de contabilidade
No processo de criação de um artigo, é obrigatório identificar o tipo de contabilidade do mesmo.
Descrição |
Embalagens |
Matérias Primas |
Mercadorias |
Produtos acabados e intermédios |
Serviços |
Subprodutos |
Transporte |
Vasilhame |
Tabelas secundárias
Por vezes é necessário ter acesso aos ID's internos para preenchimento de alguns campos, como por exemplo taxaiva_id
e unidade_id
.
A maneira mais fácil de obter o ID relativo a uma linha de base de dados, é editando a ficha da linha (em qualquer formulário) e olhando para o seu URL:
A última identificação do URL é sempre correspondente ao ID da base da dados, no caso acima exemplificativo o ID tem o número: 4
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.
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
-
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.
-
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.
-
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.
-
O documento é sempre criado com o estado de terminado/finalizado.
-
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.
-
Os campos
desconto_final
, modo_expedicao_id
, despesa_transporte_taxaiva_id
e despesa_transporte_valor
não são obrigatórios.
-
Para preenchimento das despesas de transporte, os campos acima mencionados são todos obrigatórios.
-
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.
-
O valor do campo
desconto_final
é unitário
-
O valor do campo
desconto
nas linhas de artigos é percentual
-
O valor do campo
forma_pagamento
contempla tanto o código como a descrição
-
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
-
Se o documento já tiver sido visualizado é necessário, para efeitos da Autoridade Tributária, justificar o porquê da nova visualização.
-
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
-
O documento pode já ter sido enviado ao cliente - se a opção automática de envio estiver activada na subscrição.
-
Na criação do documento via API é devolvido se o email foi ou não já enviado.
-
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
-
Apenas os campos
codigo
e nome
são de preenchimento obrigatório.
-
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
-
Os campos
id
, codigo
e nome
são de preenchimento obrigatório.
-
Se não for atribuído um valor ao campo do
contribuinte
, será assumido 999999990.
-
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
-
O campo
valor
aceita os formatos de inteiro e texto.
-
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
}
Criar artigo
Cria um novo artigo para ser utilizado no momento da facturação.
NOTAS
-
Os campos
referência
, descrição
, taxaiva_id
, unidade_id
e tipo_contabilidade
são de preenchimento obrigatório.
-
Para preenchimento dos valores
taxaiva_id
e unidade_id
é necessário aceder às respectivas tabelas em Login > Administração e obter o ID.
POST
https://facturalusa.pt/api/artigos/criar
Lista de parâmetros
{
'referencia': 'A001',
'descricao': 'Chapéus de cor',
'taxaiva_id': 4,
'unidade_id': 2,
'tipo_contabilidade': 'Mercadorias',
'preco_custo': 5,
'preco_venda': 12.30,
'observacoes': '',
}
Conteúdo da resposta
{
'msg': 'Artigo criado com sucesso!',
'id': 20
}
Actualizar artigo
Actualiza os dados existentes de um artigo.
NOTAS
-
Os campos
id
, referência
, descrição
, taxaiva_id
, unidade_id
e tipo_contabilidade
são de preenchimento obrigatório.
-
Para preenchimento dos valores
taxaiva_id
e unidade_id
é necessário aceder às respectivas tabelas em Login > Administração e obter o ID.
-
A alteração dos campos referência e descrição está sujeito a verificação de bloqueio. Será devolvida uma mensagem de erro se se justificar.
PUT
https://facturalusa.pt/api/artigos/actualizar
Lista de parâmetros
{
'id': 77,
'referencia': 'A001',
'descricao': 'Chapéus de cor amarelo',
'taxaiva_id': 4,
'unidade_id': 2,
'tipo_contabilidade': 'Mercadorias',
'preco_custo': 5,
'preco_venda': 12.30,
'observacoes': '',
}
Conteúdo da resposta
{
'msg': 'Artigo editado com sucesso!'
}
Procurar artigo
Devolve os dados do artigo pela pesquisa do id, referência ou descrição.
NOTAS
-
O campo
valor
aceita os formatos de inteiro e texto.
-
O campo
tipo
deve conter um dos valores: id
, referência
ou descrição
.
POST
https://facturalusa.pt/api/artigos/procurar
Lista de parâmetros
{
'valor': '',
'tipo': ''
}
Conteúdo da resposta
{
'msg': 'Artigo encontrado com sucesso!',
'id': '',
'referencia': '',
'descricao': '',
'taxaiva_id': '',
'unidade_id': '',
'tipo_contabilidade': '',
'preco_custo': '',
'preco_venda': '',
'observacoes': '',
'referencia_bloqueado': TRUE/FALSE,
'descricao_bloqueado': TRUE/FALSE
}
Stock do artigo
Devolve a quantidade em stock de determinado artigo pelos campos id, referência ou descrição.
NOTAS
-
O campo
valor
aceita os formatos de inteiro e texto.
-
O campo
tipo
deve conter um dos valores: id
, referencia
ou descricao
.
-
A quantidade é devolvida com 5 casas decimais.
-
O campo
quantidade_disponivel
representa o stock real disponível.
-
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,
}