Documentação API

storage
Introdução
settings
Métodos
attachment
Anexos

Introdução

Esta API permite que sejam desenvolvidas soluções informáticas que integrem o Keyinvoice de forma a poder centralizar as suas facturas, encomendas, clientes e produtos.

A nossa API utiliza um WebService (SOAP) detalhadamente documentado, o que lhe permite criar as suas aplicações ou sites com comunicação à sua aplicação de facturação Keyinvoice.

Só precisa de ter uma conta no Keyinvoice, e a partir deste gerar o identificador - API_KEY - que lhe permitirá integrar o seu software de facturação com as suas soluções desenvolvidas à medida.

Se por algum motivo o seu identificador API_KEY ficar comprometido, pode gerar um novo na sua aplicação Keyinvoice. Recomendamos que mantenha este identificador seguro, de forma a proteger os seus dados.

O serviço está acessível através do endereço https://login.keyinvoice.com/API3_ws.php?wsdl.

Todos os parâmetros devem ser passados, (a assinatura dos métodos tem de ser respeitada), mas os 'Parâmetros não vazios', marcados com *, são obrigados a ter conteúdo, diferente de string vazia ('').

Tipicamente, se a resposta for um array, a posição [0] contém o código de resposta, e a posição [1], se existir, contém os dados relevantes de resposta desse método. Se a resposta for um objecto, então a posição ->RC contém o código de resposta e a posição ->DAT contém os dados relevantes de resposta desse método. Existem algumas excepções que poderão consultar nesta documentação.

A api permite fazer muitas das funcionalidades do Keyinvoice, consulte o separador "métodos" para conhecer todas as funcionalidades disponíveis.
A API está limitada a 5000 chamadas diárias. A utilização da mesma continuará a ser gratuita, no entanto, terá este limite diário. Caso pretenda utilizar diariamente mais do que o limite definido poderá adquirir pack's adicionais. Mais informações contacte-nos através do email suporte@keyinvoice.com


Exemplo PHP
Neste exemplo vamos utilizar vários métodos para criar:
-Uma Sessão válida
-Um cliente
-Um artigo
-Uma fatura utilizando o cliente e artigo criado
-Enviar Documento por email

 
	$WS_URL = 'https://login.keyinvoice.com/API3_ws.php?wsdl';
 $API_KEY = 'INSIRA A SUA CHAVE AQUI';
 
 
 $soap = new soapclient( $WS_URL );
 $result = $soap->authenticate( $API_KEY );
 $APISession = $result[1];

 //DEFINIR DADOS CLIENTE
 $nif = "510072801";
 $name = "Keyinvoice";
 $address = "Alameda dos Oceanos, 41-O 32A";
 $postalCode = "1990-203";
 $locality = "LISBOA";
 $phone = "211933556";
 $fax = "";
 $email = "suporte@keyinvoice.com";
 $obs = "Cliente de teste";
 //CRIAR CLIENTE
 $create_client = $soap->insertClient( $APISession, $nif, $name, $address, $postalcode, $locality, $phone, $fax, $email, $obs );
 print_r( $create_client );
 

 //DEFINIR DADOS PRODUTO
 $ref          = "0022";
 $designation  = "Produto de teste";
 $shortName    = "Ptest";
 $tax          = "23";
 $obs          = "teste";
 $isService    = "0";
 $hasStocks    = "0";
 $active       = "1";
 $shortDesc    = "Descricao 123";
 $longDesc     = "Descricao longa, teste 123.";
 $price        = "100";
 $vendorRef    = "";
 $ean          = "";
 //CRIAR PRODUTO
 $product = $soap->insertProduct( $APISession, $ref, $designation, $shortName, $tax, $obs, $isService, $hasStocks, $active, $shortDesc, $longDesc, $price, $vendorRef, $ean);
 print_r($product);
 

 //DEFINE O TIPO DE DOCUMENTO 4 = FATURA
 $doctype = 4;
 

 $obs = "";
 $opt_name = "";
 $opt_nif = "";
 $opt_address = "";
 $opt_locality = "";
 $opt_postalCode = "";
 $docRef = "";
 //CRIAR CABECALHO DO DOCUMENTO PASSANDO O NIF DO CLIENTE CRIADO
 $insert_document    = $soap->insertDocumentHeader( $APISession, $nif , $doctype, $obs, $opt_name, $opt_nif, $opt_address, $opt_locality, $opt_postalCode,  $docRef );
 print_r($insert_document);
 //DEFINE O ID DO DOCUMENTO
 $idDocTemp          = $insert_document[1];
 

 //NAO E NECESSARIO DEFINIR ESTA INFORMACAO, O SISTEMA VAI BUSCAR OS VALORES DEFINIDOS NO PRODUTO
 $qt = "";
 $price = "";
 $tax = "";
 $prodDesc = "";
 $discount = "";
 //CRIAR UMA LINHA PARA O DOCUMENTO PASSANDO A REF DO PRODUTO CRIADO
 $insert_document_line = $soap->insertDocumentLine( $APISession, $idDocTemp, $doctype, $ref, $qt, $price, $tax, $prodDesc, $discount );
 print_r( $insert_document_line );
 

 //FECHAR O DOCUMENTO, SE O DOCUMENTO NAO FOR FECHADO FICARA EM RASCUNHO NO SISTEMA
 $close_document = $soap->closeDocument( $APISession, $idDocTemp, $doctype );
 //DEFINIR O ID DO DOCUMENTO FINAL
 $idDocTemp      = $close_document[1];
 print_r( $close_document );
 

 //DEFINIR OS DADOS PARA O ENVIO DO EMAIL
 $email_destinations = 'suporte@keyinvoice.com';
 $email_subject = 'Titulo email';
 $email_body = 'Segue em anexo o documento!';
 //ENVIAR EMAIL COM DOC EM ANEXO. 
 //AS CONFIGURACOES PARA O ENVIO DO EMAIL TEEM QUE ESTAR BEM CONFIGURADAS NA SUA CONTA KEYINVOICE!
 $email = $soap->sendDocumentPDF2Email ( $APISession, $idDocTemp, $doctype, $email_destinations, $email_subject, $email_body );
 print_r( $email );
 die;

	

Secções

SESSION
TABLES
TABLES-FAMILIES
TABLES-COUNTRIES
TABLES-CURRENCIES
CLIENTS
CLIENTS-ALTADDRESS
CLIENTS-ENTITIES
SELLERS
PRODUCTS
DOCUMENTS
CRM
STATS

Secção documents

Métodos

countDocuments
documentsList
documentsList_byClient
documentsList_custom
documentsList_byClient_custom
documentsDraftsList
documentExists
getDocument
getDocument_bySeries
getDocumentInfo
getDocumentCertificate
getDocumentCertificateInfo
getDocumentPDF
getDocumentPDFSigned
getDocumentPDFLink
getDocumentPDFLink_bySeries
sendDocumentPDF2Email
sendDocumentPDFSigned2Email
sendDocumentPDF2Email_bySeries
insertDocumentHeader
insertEntityOrder
insertDocumentHeader_additionalInfo
setDocumentHeaderField
insertDocumentAlternativeCurrency
closeDocument
documentCommunication
documentCommunication_bySeries
generateMBRef
addMBRef
settleInvoice
checkIfSettle
setDocumentVoid
deleteDocumentDraft
getDocumentTalao
getDocumentLines
getDocumentLines_bySeries
getDocumentLineCS
getDocumentLineInfo
insertDocumentLine
insertDocumentLineCS
changeDocumentLineTax
DocumentTransport

Método countDocuments

Descrição

Conta o número total de documentos do tipo indicado gravados na base de dados.

Parâmetros

[sid]* - identificador de sessão
[docType]* - tipo de documento. Ver tabela de Tipos de documentos possíveis.

Respostas possíveis

::array ( [0]=> 1, [1]=>(número de resultados) )
::array ( [0]=> -4 )
::array ( [0]=> -5 )

Códigos de Respostakeyboard_arrow_down

[RC 1] Acção efectuada com sucesso.
[RC 0] Código de resposta não documentado.
[RC -1] Autenticação falhada. Verificar a Chave API_KEY
[RC -2] Faltam dados de configuração. Verifique a sua conta.
[RC -3] Não foi possível criar uma sessão (5 tentativas).
[RC -4] Sessão Expirada. Este código de sessão já não é válido. (TTL 3600s )
[RC -5] Erro de parâmetros. Restrição de «Parâmetros não vazios» não respeitada
[RC -6] Funcionalidade indisponível para a sua licença.
[RC -7] Tipo de documento inválido.
[RC -12] Não foi possível gerar os dados do ficheiro para envio
[RC -101] Não foi possível gravar os dados do cliente!
[RC -102] Não foi possível encontrar o cliente pelo NIF indicado!
[RC -104] Não foi possível ler os dados do cliente!
[RC -105] Não foi possível eliminar o cliente!
[RC -111] Não foi possível criar novo registo de Morada Alternativa
[RC -112] Não foi possível alterar o registo de Morada Alternativa
[RC -113] Não foi possível carregar o registo de Morada Alternativa
[RC -114] Não foi possível apagar o registo de Morada Alternativa
[RC -121] Não foi possível carregar informação do cliente ao qual pretende associar a entidade
[RC -122] Não foi possível carregar informação da entidade indicada
[RC -151] Não foi possível gravar os dados do contacto!
[RC -152] Não foi possível encontrar o contacto pelo ID indicado!
[RC -154] Não foi possível ler os dados do contacto!
[RC -155] Não foi possível eliminar o contacto!
[RC -156] Não foi possível encontrar o contacto!
[RC -201] Não foi possível gravar os dados do artigo!
[RC -202] Não foi possível ler os dados do artigo!
[RC -203] Não foi possível criar o artigo: esta referência já existe.
[RC -204] O artigo não existe.
[RC -205] Não foi possível apagar o artigo.
[RC -206] Não foi possível gravar a taxa de IVA.
[RC -211] Não foi possível copiar a imagem a partir do URL indicado.
[RC -301] Não foi possível gravar o cabeçalho.
[RC -302] Não foi possível gravar a linha de documento.
[RC -303] Não foi possível ler os dados do cabeçalho para o código indicado.
[RC -304] Não foi possível gravar definitivamente o cabeçalho com o código indicado.
[RC -305] O documento com código indicado não existe.
[RC -306] Não foi possível gravar a linha do documento.
[RC -307] Não foi possível guardar os detalhes do cabeçalho.
[RC -308] Não foi possível guardar o documento.
[RC -311] Não foi possível enviar o email. SMTP inactivo ou com configuração errada.
[RC -312] Não foi possível enviar o email. Erro na geração do ficheiro.
[RC -321] Ocorreu um erro na comunicação com a Autoriadade Tributária
[RC -322] Dados inválidos, ou funcionalidade inexistente no Sistema de Facturação.
[RC -331] Não foi possível adicionar a informação de Cor/Tamanho à linha do documento
[RC -340] Erro ao ler Dcoumento.
[RC -341] O Documento não se encontra fechado, pelo qual não pode ser faturado.
[RC -342] O Documento encontra-se anulado ou já foi convertido.
[RC -343] Erro ao tentar ler Série de Documento.
[RC -344] Erro ao gravar cabeçalho do documento.
[RC -345] Erro ao gravar a linha do documento
[RC -401] Não foi possível gravar os dados do fornecedor!
[RC -402] Não foi possível encontrar o fornecedor pelo NIF indicado!
[RC -403] Não foi possível carregar os dados do fornecedor indicado
[RC -404] Não foi possível ler os dados do fornecedor!
[RC -405] Não foi possível eliminar o fornecedor!
[RC -501] Não foi possível criar o novo registo de cor/tamanho
[RC -511] O País indicado não existe
[RC -512] O País indicado já existe
[RC -513] Não foi possível gravar o novo país.
[RC -521] Não foi possível gravar a nova moeda.
[RC -522] Não foi possível ler o registo de moeda indicado.
[RC -523] Não foi possível actualizar a moeda.
[RC -524] A moeda indicada não existe.
[RC -525] Não foi possível apagar a moeda.
[RC -526] Não foi possível gravar um valor de conversão para esta moeda.
[RC -527] Não foi possível associar esta moeda como segunda moeda do documento.
[RC -528] Não foi possível gravar o documento com os dados de segunda moeda.
[RC -551] Não foi possível gravar os dados da família!
[RC -552] Não foi possível encontrar a família pelo identificador indicado!
[RC -553] Não foi possível carregar os dados da família indicada
[RC -554] Não foi possível ler os dados da família!
[RC -555] Não foi possível eliminar a família!
[RC -600] Atingiu o limite máximo de chamadas de API
[RC -601] Atenção! Preço de Venda inferior ao preço de Custo

Tipos de dados keyboard_arrow_down

CompanyResponse
Companies
Company
PersonResponse
Persons
Person
PersonResponse_custom
Persons_custom
Person_custom
ProductResponse
Products
Product
ProductResponse_custom
Products_custom
Product_custom
ProductResponseDetails
ProductsDetails
ProductDetail
Prices
Price
ProductInfoResponse
ProductInfo
FamilyResponse
Families
Family
SubFamily
SubFamilies
Models
Model
BrandResponse
Brands
Brand
DocumentResponse
Documents
Document
DocumentDetailsResponse
DocumentsDetails
DocumentDetail
DocumentLineResponse
DocumentLines
DocumentLine
DocumentLineDetailsResponse
DocumentDetailsLines
DocumentDetailsLine
AltAddressResponse
AltAddresses
AltAddress
TableResponse
Table
TableItem
MBRefResponse
MBRef
DocumentCertificateResponse
DocumentsCertificate
DocumentCertificate
DocumentCertificateInfoResponse
DocumentCertificateInfo
DocumentQRCodeInfoResponse
DocumentQRCodeInfo
DiscountResponse
Discounts
Discount
CurrencyResponse
Currencies
Currency
SalesmanResponse
Salesmans
Salesman
ContactResponse
Contacts
Contact
ClientHistoryResponse
ClientHistoryDocuments
ClientHistoryDocument
WarehouseStockResponse
StockResponse
Stock
AllDocsResponse
DocsResp
Docs
DocsLines
BatchNumbersLines
TableBatchNumResponse
TableBatchNum
TableBatchNumItem
AllDocsResponseTESTE
DocsRespTESTE
DocsTESTE
DocsLinesTESTE
DocResponse
PaymentMethodResponse
PaymentMethods
PaymentMethod
ProductItemResponse
ProductItems
ProductItem

Tipos de documentos keyboard_arrow_down

> Documentos de Venda:
4 - Factura de cliente
5 - Vendas-a-dinheiro
7 - Créditos financeiros (clientes)
13 - Encomenda de cliente
15 - Guia de remessa
16 - Guia de transporte
32 - Fatura Simplificada
34 - Fatura-Recibo
6 - Devoluções de clientes

> Documentos de Compra:
3 - Factura de compra
24 - Vendas-a-dinheiro de fornecedor
23 - Encomendas de fornecedor
33 - Fatura Simplificada de fornecedor
11 - Crédito financeiro de fornecedor
© Copyright 2023    |    Termos e Condições    |    Políticas de Privacidade