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:
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.
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.
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"}'
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 |
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 |
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 |
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 aceites para quando há a criação de uma conta de cliente.
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.
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.
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.
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.
desconto_final, modo_expedicao_id, despesa_transporte_taxaiva_id e despesa_transporte_valor não são obrigatórios.
modo_expedicao_id e despesa_transporte_taxaiva_id é necessário aceder às respectivas tabelas em Login > Administração e obter o ID.
desconto_final é unitário
desconto nas linhas de artigos é percentual
forma_pagamento contempla tanto o código como a descrição
descricao_detalhada é facultativo e serve apenas de apoio ao artigo em questão (por exemplo para mencionar opções de Tamanho;Cor)
{
'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': ''
}
{
'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
}
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': ''
}
{
'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
}
Sempre que se justifique pode gerar novamente o PDF do documento (mesmo que já tenha sido gerado) e será devolvido o url do ficheiro.
{
'id': '121',
'tipo_documento': 'FT',
'original': FALSE,
'motivo': ''
}
{
'msg': 'PDF gerado com sucesso!',
'pdf': 'url'
}
Pode usufruir dos nossos serviços para que o email seja enviado ao cliente com o documento PDF em anexo.
assunto e mensagem não são de preenchimento obrigatório.
{
'id': '121',
'tipo_documento': 'FT',
'email': 'exemplo@exemplo.com',
'assunto': '',
'mensagem': ''
}
{
'msg': 'Email enviado com sucesso!'
}
Cria um novo cliente para ser utilizado no momento da facturação.
codigo e nome são de preenchimento obrigatório.
contribuinte, será assumido 999999990.
{
'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': '']]
}
{
'msg': 'Cliente criado com sucesso!',
'id': 10
}
Actualiza os dados existentes de um cliente.
id, codigo e nome são de preenchimento obrigatório.
contribuinte, será assumido 999999990.
nome, codigo, contribuinte está sujeito a verificação de bloqueio.
Será devolvida uma mensagem de erro se se justificar.
{
'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': '']]
}
{
'msg': 'Cliente editado com sucesso!'
}
Devolve os dados do cliente pela pesquisa do id, código ou contribuinte.
valor aceita os formatos de inteiro e texto.
tipo deve conter um dos valores: id, codigo ou contribuinte.
{
'valor': '',
'tipo': ''
}
{
'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
}
Cria um novo artigo para ser utilizado no momento da facturação.
referência, descrição, taxaiva_id, unidade_id e tipo_contabilidade são de preenchimento obrigatório.
taxaiva_id e unidade_id é necessário aceder às respectivas tabelas em Login > Administração e obter o ID.
{
'referencia': 'A001',
'descricao': 'Chapéus de cor',
'taxaiva_id': 4,
'unidade_id': 2,
'tipo_contabilidade': 'Mercadorias',
'preco_custo': 5,
'preco_venda': 12.30,
'observacoes': '',
}
{
'msg': 'Artigo criado com sucesso!',
'id': 20
}
Actualiza os dados existentes de um artigo.
id, referência, descrição, taxaiva_id, unidade_id e tipo_contabilidade são de preenchimento obrigatório.
taxaiva_id e unidade_id é necessário aceder às respectivas tabelas em Login > Administração e obter o ID.
{
'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': '',
}
{
'msg': 'Artigo editado com sucesso!'
}
Devolve os dados do artigo pela pesquisa do id, referência ou descrição.
valor aceita os formatos de inteiro e texto.
tipo deve conter um dos valores: id, referência ou descrição.
{
'valor': '',
'tipo': ''
}
{
'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
}
Devolve a quantidade em stock de determinado artigo pelos campos id, referência ou descrição.
valor aceita os formatos de inteiro e texto.
tipo deve conter um dos valores: id, referencia ou descricao.
quantidade_disponivel representa o stock real disponível.
quantidade_encomendas representa o stock que está pendente para facturação nas encomendas.
{
'valor': '',
'tipo': ''
}
{
'quantidade_disponivel': 10.00000,
'quantidade_encomendas': 5.00000,
}