🇬🇧 ENGLISH | 🇵🇹 PORTUGUESE

API para SOFTWARE DE FATURAÇÃO ONLINE - Bill.pt


SDKs para ajudar desenvolvimento e exemplos de código

PHP SDK & Exemplos NODEJS SDK & Exemplos PYTHON SDK & Exemplos

Bem vindo

A nossa API permite a integração entre o nosso Software de Faturação e diferentes sistemas. A documentação da API encontra-se divida entre 4 àreas. As nossas respostas são sempre feitas em formato JSON.

  • Request - Endereço e Tipo de Pedido
  • Parameters - Valores que o pedido aceita
    • Campo 1 Parametros obrigatórios
    • Campo 2 Poderá ser obrigatório. Depende de outro parametro
  • Response - Resposta do servidor
  • Error - Os códigos dos erros que são devolvidos

Os pedidos podem ser feitos em formato:GET POST PATCH DELETE essa informação estará presente em cada pedido.

O URL base dos pedidos é :
https://app.bill.pt Produção
https://dev.bill.pt Test Server

Versões

A versão mais actual é: 1.0

Erros

Os erros são devolvidos no seguinte formato JSON : 

              {"error":["2.email","1.password"]}

Um objecto com um array de erros. Poderão existir multiplos erros no pedido. Para interpretar os erros poderá analisar a seguinte tabela

3 tipos de Erros:

  • 1.password - codigo_do_erro.nome_do_parametro
  • 100.quantidade.1 - codigo_do_erro.nome_do_campo.valor
  • 200 - código_do_erro

Assim sendo o primeiro valor númerico indica sempre o código do erro. O nome do campo poderá existir estando sempre separado do código do erro pelo caracter "." Este nome do campo poderá não ser apresentado em snake_case. Então imposto_id poderá aparecer como 1.imposto id . Por último também separado pelo caracter "." poderá aparecer um valor. Analisando o código do erro é simples perceber quantos valores recebemos de volta. Código de 0 a 99 vem com código.nome_do_campo. Código 100 a 199 vem com código.nome_do_campo_valor. Código superior a 200 vem sem valores extra.

Tabela de Erros
Código Significado
Código: 0 .. 99
1.nome_do_campo Significa que o campo é obrigatório.
2.nome_do_campo O email não é um email válido.
3.nome_do_campo O campo deve ser único. Aparentemente já existe na base de dados.
4.nome_do_campo O campo deve ser confirmado.
5.nome_do_campo O campo deve ser boolean.
6.nome_do_campo O campo deve ser um conjunto de caracteres normais.
7.nome_do_campo O campo deve ser um numero inteiro.
8.nome_do_campo O campo deve ser alpha numerico.
9.nome_do_campo O campo não tem um valor válido.
10.nome_do_campo O campo deve ser númerico.
Código: 100 .. 199
100.nome_do_campo.valor O campo deve ter no minimo :valor caracteres.
101.nome_do_campo.valor O campo não deve ter mais do que :valor caracteres
102.nome_do_campo.valor Existe um documento certificado com a data mais recente nesta mesma serie. Datado de :valor
Código: 200+
200 Dados de login incorrectos.
201 Não conseguiu criar o token.
202 Token não fornecido.
203 A sessão expirou.
204 Já se encontra activo.
205 Utilizador Inválido
206 NIF não é válido.
207 Utilizador não pertence a esta conta.
208 Token inválido.
209 O valor indicado.
210 O utilizador não existe nesta empresa.
211 O utilizador já foi usado.
212 O ID do utilizador é obrigatorio.
213 Não pode editar os utilizadores.
214 Código Postal: no formato incorrecto. Aceite XXXX-XXX ou XXXX.
215 Ficheiro invalido.
216 Um dos utilizadores não pertence mais a esta conta.
217 Um dos contatos não pertence mais a esta conta.
218 Um dos itens não pertence mais a esta conta.
219 A Categoria não pertence a esta empresa.
220 O tipo não pertence a esta empresa.
221 A unidade de medida não pertence a esta empresa.
222 O elemento que está a tentar apagar já foi utilizado.
223 O metodo de pagamento não pertence a esta empresa.
224 O metodo de Expedicao não pertence a esta empresa.
225 O Contato não pertence a esta empresa.
226 Já existe uma serie com este nome.
227 A serie não pertence a esta empresa.
228 A viatura não pertence a esta empresa.
229 O Imposto não pertence a esta empresa.
230 O item não pertence a esta conta.
231 O código do não é unico.
232 Não foi possivel detectar o código. O ficheiro não cumpre as regras.
233 Não foi possivel detectar o código ou NIF. O ficheiro não cumpre as regras.
234 O ficheiro aparenta estar incorrecto não foi possivel encontrar coluna productCode.
235 Apenas pode apagar documentos em rascunho.
236 O documento tem um documento de pagamento associado por esse motivo não pode ser anulado.
237 O documento já não é deste mês por isso não pode ser anulado.
238 Não pode anular um documento que já foi emitido à mais de 5 dias.
239 A data de descarga não é valida. Deveria ser superior às de carga e data do documento.
240 A data de carga não é valida. Deveria ser superior à data do documento.
241 O prazo de vencimento não pode ser menor que a data do documento.
242 Existe um documento certificado com a data mais recente nesta mesma serie. Datado de :valor
243 O total do documento não pode ser menor que zero.
244 Não pode emitir uma fatura com este valor para consumidor final.
245 O utilizador não tem permissões. Verifique as permissões.
246 Se o documento é convertido por um documento retificativo este documento não poderá ser mais anulado. Se desejar efectuar alterações a este documento poderá emitir um documento retificativo Nota de Débito ou crédito associado a este documento.
247 A loja não pertence a esta conta.
248 O token não é válido.
249 O tipo de comunicação não é valido para este documento.
250 Deve definir a sua password e utilizador da Autoridade Tributaria.
251 O documento já foi convertido por outro. Anule primeiro esse documento.
252 Este NIF está a ser usado noutra conta. Apenas é permitida uma conta por empresa. Se acreditar que se trata de um erro contacte suporte@bill.pt.
253 O nif já está associado a um contacto nesta conta.
254 Atingiu o limite de documentos mensais que o seu plano permite. Verifique o seu plano atual.
255 Atingiu o limite de funcionários que o seu limite permite. Verifique o seu plano atual.
256 Atingiu o limite de armazéns/lojas que o seu limite permite. Verifique o seu plano atual.
257 O seu plano atual não permite gestão de stock.
258 Não tem permissão para fazer esta accão.
259 Não está permitido a usar esta conta.
260 Não tem permissões para gerir compras.
261 Não tem permissões para gerir vendas.
262 Não tem permissões para gerir recibos.
263 O estado não pertence a esta empresa.
264 Código Invalido.
265 Não está no seu horario de trabalho.
266 Nota de Crédito ou Débito são documentos retificativos de fatura. Todas as linhas deste documento devem fazer referencia ao documento original. Uma ou mais linhas deste documento não fazem referencia ao documento original.
267 Não está no seu horario de trabalho.
268 Licença já terminada.
269 Licença já foi utilizada por esta empresa.
270 Não enviou isencao então deveria enviar imposto ou imposto_id.
271 Não enviou isencao então deveria enviar imposto ou imposto_id.
271 Não é possivel vender um produto a preço zero. Mesmo sendo uma oferta deverá colocar um valor e aplicar desconto de 100%.
272 O documento não se encontra terminado.
273 A imagem deve ser jpg ou jpeg e tamanho máximo 1200x800.
274 O motivo de isenção é invalido.
275 A fatura simplificada não aceita isenção de IVA. Deverá criar uma fatura comum.
276 Não foi possivel comunicar o documento.
277 Falhou o login. Verifique os seus dados de login. Teste os seus dados em: https://www.acesso.gov.pt/v2/login
288 Não pode usar como filtro uma loja a qual não está associado o seu utilizador.
289 Documento já se encontra anulado.
291 Este elemento não pertece à sua conta por esse motivo não pode ser eliminado.
292 Uma fatura deverá ser emitida dentro do prazo legal para o efeito. Devendo ser emitida no mesmo mês ou no mês seguinte antes do dia 15. (para exportações).
300 Esta serie não pode ser usada para criação de documentos.
301 O seu produto composto não tem qualquer produto na sua composição.
302 O limite da fatura simplificada são 100 euros mais IVA para não retalhistas/vendedores ambulantes
303 Fatura simplificada não pode ter um valor superior a 1000 euros.
304 Fatura simplificada não pode ter prestação de serviços se for superior a 100 euros. Utilize Fatura ou Fatura Recibo.
305 Fatura simplificada não pode ser superior a 100 euros caso seja para sujeito passivo de IVA. Utilize Fatura ou Fatura Recibo.
306 Simbolos invalidos no nome da Série.
307 Série não percente a esta conta.
308 O utilizador não tem permissões.
309 A serie que está a tentar utilizar não foi reportada à autoridade tributária. Informação
311 O contato já tem um documento oficial criado. Não poderá trocar o NIF.

Como Obter Chaves da API

No Bill tratamos cada utilizador de forma independente. Então uma conta poderá ter 2 utilizadores e um deles não ter acesso à API.

Para gerar uma chave de api poderá aceder a conta do Bill e na Gestão de utilizadores dar a permissão de API ao utilizador e gerar uma chave para o mesmo.

Agora o utilizador terá acesso à sua chave quando acede as configurações da sua conta. Poderá também aceder à chave do utilizador utilizando o seguinte pedido.

POST api/1.0/auth/login

Parameters
Nome Tipo Example
email 1 String E-Mail example@example.com
password 1 String 1wh72jja8k2jah
Response 
              {
              "id": 1,
              "nome": "John Doe",
              "email": "johndoe@example.com",
              "api_token": "4zA1HOjFTqXzv5kpCfEA58WG2kkXt39dw31vcVARlBCtajowlFNoxtdSso504hL4H6OwlxAQQbOC4lWqJutZNO3AniKwl3Yba6Zn2jC4t6QbeKIcUnESC0GpOxpuy2dM"
            }

Poderá Utilizar enviar o seu Token no Header. Authorization: Bearer SEU_TOKEN, se desejar em qualquer pedido da API. Para evitar expor o token em pedidos GET no url.

Para Desenvolvedores

Desenvolvedores que não tenham acesso a uma conta oficial devem pedir ao suporte a criação de uma conta especial de modo a poderem ter acesso a API para testes.

Limites

Os limites da nossa api são de: 100 pedidos por minuto. Para controlar os limites são fornecedidos 2 headers devolvidos em cada pedido.

"x-ratelimit-limit" : 100,
"x-ratelimit-remaining" : 60

De modo a fazer uma útilização responsavel da API é aconselhavel fazer guardar alguns dados do seu lado para reduzir o número de pedidos. Também é aconselhado caso necessário fazer sincronismo de itens ou contactos de modo faseado.

Tipos de Contatos

No bill existem tipos de contatos (clientes/fornecedores). Funcionam como categorias para organizar os seus contatos. Assim poderá por exemplo criar tipo "Fornecedor", "Cliente", "Cliente Tipo 2" etc...

Ler Tipo de Contato

GET api/1.0/tipos

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
Response 
            [{
            "id": 2,
            "empresa_id": 1,
            "nome": "Categoria",
            "visivel": 1,
            "created_at": "2016-04-29 18:18:27",
            "updated_at": "2016-04-29 18:18:27"
          }]

Criar Tipo de Contato

POST api/1.0/tipos

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
nome 1 String (30) Categoria 1
Response 
          {
            "nome": "Categoria",
            "updated_at": "2016-04-29 18:22:26",
            "created_at": "2016-04-29 18:22:26",
            "id": 3,
            "empresa_id": 1
          }

Update Tipo de Contato

PATCH api/1.0/tipos/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
nome String (30) Categoria 1
visivel Boolean 0
Response 
{
  "id": 3,
  "empresa_id": 1,
  "nome": "Nova",
  "visivel": 1,
  "created_at": "2016-04-29 18:22:26",
  "updated_at": "2016-04-29 18:27:00"
}

Estados de Documento

O Bill permite associar estados a documentos. Isto é especial util por exemplo se quiser marcar um orçamento como pendente, aceite, entregue etc... poderá criar quantos estados quiser e aplicar em qualquer documento.

Ler Estados

GET api/1.0/estados

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
Response 
            [
  {
    "id": 2,
    "empresa_id": 1,
    "nome": "Por usar",
    "usado": 0,
    "principal": 0,
    "visivel": 1,
    "created_at": "2017-02-01 14:20:59",
    "updated_at": "2017-02-01 14:20:59"
  }
]

Criar Estados

POST api/1.0/estados

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
nome 1 String (30) Em espera
principal Boolean 0
Response 
{
    "id": 2,
    "empresa_id": 1,
    "nome": "Em espera",
    "usado": 0,
    "principal": 0,
    "visivel": 1,
    "created_at": "2017-02-01 14:20:59",
    "updated_at": "2017-02-01 14:20:59"
  }

Update Estado

PATCH api/1.0/estados/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
nome 1 String (30) Em espera
principal Boolean 0
visivel Boolean 0
Response 
{
    "id": 2,
    "empresa_id": 1,
    "nome": "Em espera",
    "usado": 0,
    "principal": 0,
    "visivel": 1,
    "created_at": "2017-02-01 14:20:59",
    "updated_at": "2017-02-01 14:20:59"
  }

Apagar Estado

DELETE api/1.0/estados/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
Response 
{}

Mudar Estado de Documento

POST api/1.0/estados

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
documento_id 1 ID do documento 133
modulo_estado_id 1 ID do Estado 234
Response 
{}

Tipos De Documento

São válidos os seguintes pedidos:

No Bill existem váriados tipos de documento, poderá obter as informações sobre os tipos de documento disponiveis e os respectivos ID no seguinte pedido:

Ler tipos de documento

GET api/1.0/tipos-documento

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
Response 
           [  
           {  
           "id":1,
           "tipificacao":"FT",
           "nome":"Fatura",
           "categoria":"faturas"
         },
         {  
         "id":2,
         "tipificacao":"FS",
         "nome":"Fatura Simplificada",
         "categoria":"faturas"
       },
       {  
       "id":3,
       "tipificacao":"FR",
       "nome":"Fatura Recibo",
       "categoria":"faturas"
     },
     {  
     "id":4,
     "tipificacao":"ND",
     "nome":"Nota de D\u00e9bito",
     "categoria":"faturas"
   },
   {  
   "id":5,
   "tipificacao":"NC",
   "nome":"Nota de Cr\u00e9dito",
   "categoria":"faturas"
 },
 {  
 "id":6,
 "tipificacao":"GT",
 "nome":"Guia De Transporte",
 "categoria":"guias"
},
{  
  "id":7,
  "tipificacao":"GR",
  "nome":"Guia De Remessa",
  "categoria":"guias"
},
{  
  "id":8,
  "tipificacao":"GC",
  "nome":"Guia de Consigna\u00e7\u00e3o",
  "categoria":"guias"
},
{  
  "id":9,
  "tipificacao":"GA",
  "nome":"Guia de Movimenta\u00e7\u00e3o de a",
  "categoria":"guias"
},
{  
  "id":10,
  "tipificacao":"GD",
  "nome":"Guia \/ Nota de Devolu\u00e7\u00e3o",
  "categoria":"guias"
},
{  
  "id":11,
  "tipificacao":"NENC",
  "nome":"Nota de Encomenda",
  "categoria":"encomendas"
},
{  
  "id":12,
  "tipificacao":"ORC",
  "nome":"Or\u00e7amento",
  "categoria":"orcamentos"
},
{  
  "id":13,
  "tipificacao":"FPF",
  "nome":"Fatura Pro-Forma",
  "categoria":"orcamentos"
},
{  
  "id":14,
  "tipificacao":"VFT",
  "nome":"V\/Fatura",
  "categoria":"compras"
},
{  
  "id":15,
  "tipificacao":"VFR",
  "nome":"V\/Fatura Recibo",
  "categoria":"compras"
},
{  
  "id":16,
  "tipificacao":"VFS",
  "nome":"V\/Fatura Simplificada",
  "categoria":"compras"
},
{  
  "id":17,
  "tipificacao":"VND",
  "nome":"V\/Nota de D\u00e9bito",
  "categoria":"compras"
},
{  
  "id":18,
  "tipificacao":"VNC",
  "nome":"V\/Nota de Cr\u00e9dito",
  "categoria":"compras"
},
{  
  "id":19,
  "tipificacao":"VGR",
  "nome":"V\/Guia de Remessa",
  "categoria":"compras"
},
{  
  "id":20,
  "tipificacao":"VGT",
  "nome":"V\/Guia de Transporte",
  "categoria":"compras"
},
{  
  "id":21,
  "tipificacao":"VNENC",
  "nome":"V\/Nota de Encomenda",
  "categoria":"compras"
},
{  
  "id":22,
  "tipificacao":"VORC",
  "nome":"V\/Or\u00e7amento",
  "categoria":"compras"
},
{  
  "id":23,
  "tipificacao":"VFPF",
  "nome":"V\/Fatura Pro-Forma",
  "categoria":"compras"
},
{  
  "id":24,
  "tipificacao":"ESTK",
  "nome":"Entrada de Stock",
  "categoria":"stock"
},
{  
  "id":25,
  "tipificacao":"SSTK",
  "nome":"Saida de Stock",
  "categoria":"stock"
},
{  
  "id":26,
  "tipificacao":"SINIV",
  "nome":"Saldo Cliente",
  "categoria":"faturas"
},
{  
  "id":27,
  "tipificacao":"SINIC",
  "nome":"Saldo Fornecedor",
  "categoria":"faturas"
},
{  
  "id":28,
  "tipificacao":"RC",
  "nome":"Recibo",
  "categoria":"faturas"
},
{  
  "id":29,
  "tipificacao":"RFC",
  "nome":"Recibo Fornecedor",
  "categoria":"compras"
}
]

Ler tipos de documento por categoria

GET api/1.0/tipos-documento/CATEGORIA

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
categoria 1 String (10) Deverá enviar a categoria no URL.
São válidos: faturas, guias, orcamentos, compras
Response 
  [  
  {  
  "id":1,
  "tipificacao":"FT",
  "nome":"Fatura",
  "categoria":"faturas"
},
{  
  "id":2,
  "tipificacao":"FS",
  "nome":"Fatura Simplificada",
  "categoria":"faturas"
},
{  
  "id":3,
  "tipificacao":"FR",
  "nome":"Fatura Recibo",
  "categoria":"faturas"
},
{  
  "id":4,
  "tipificacao":"ND",
  "nome":"Nota de D\u00e9bito",
  "categoria":"faturas"
},
{  
  "id":5,
  "tipificacao":"NC",
  "nome":"Nota de Cr\u00e9dito",
  "categoria":"faturas"
},
{  
  "id":26,
  "tipificacao":"SINIV",
  "nome":"Saldo Cliente",
  "categoria":"faturas"
},
{  
  "id":27,
  "tipificacao":"SINIC",
  "nome":"Saldo Fornecedor",
  "categoria":"faturas"
},
{  
  "id":28,
  "tipificacao":"RC",
  "nome":"Recibo",
  "categoria":"faturas"
}
]

Métodos de Pagamento

Informação que deverá estar presente nos documentos. Cada método de pagamento tem um ID único associado. Para saber quais os métodos de pagamento da sua conta use o seguinte endereço.

Ler métodos de pagamento

GET api/1.0/metodos-pagamento

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
Response 
  [  
  {  
  "id":1,
  "nome":"Transfer\u00eancia ou D\u00e9bito Direct",
  "simbolo":"TB",
  "principal":1
},
{  
  "id":2,
  "nome":"Refer\u00eancia Pagamento Multibanc",
  "simbolo":"MB",
  "principal":0
},
{  
  "id":3,
  "nome":"Cart\u00e3o Cr\u00e9dito",
  "simbolo":"CC",
  "principal":0
},
{  
  "id":4,
  "nome":"Cart\u00e3o D\u00e9bito",
  "simbolo":"CD",
  "principal":0
},
{  
  "id":5,
  "nome":"Cheque",
  "simbolo":"CH",
  "principal":0
},
{  
  "id":6,
  "nome":"Cart\u00e3o Oferta",
  "simbolo":"CO",
  "principal":0
},
{  
  "id":7,
  "nome":"Compensa\u00e7\u00e3o De Saldos de Conta",
  "simbolo":"CS",
  "principal":0
},
{  
  "id":8,
  "nome":"Dinheiro Electronico",
  "simbolo":"DE",
  "principal":0
},
{  
  "id":9,
  "nome":"Letra",
  "simbolo":"LC",
  "principal":0
},
{  
  "id":10,
  "nome":"Numerario",
  "simbolo":"NU",
  "principal":0
},
{  
  "id":11,
  "nome":"Permuta de Bens",
  "simbolo":"PR",
  "principal":0
},
{  
  "id":12,
  "nome":"Ticket Restaurante",
  "simbolo":"TR",
  "principal":0
}
]

Métodos de Expedição

São válidos os seguintes pedidos:

Informação que deverá estar presente nos documentos. Cada método de expedicao tem um ID único associado. Para saber quais os métodos de expedicao da sua conta use o seguinte endereço.

Ler métodos de expedição

GET api/1.0/metodos-expedicao

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
Response 
  [{
  "id": 1,
  "nome": "Viatura Cliente",
  "usado": 0,
  "visivel": 1,
  "principal": 1
}, {
"id": 2,
"nome": "Nossa Viatura",
"usado": 0,
"visivel": 1,
"principal": 0
}, {
"id": 3,
"nome": "Transportadora",
"usado": 0,
"visivel": 1,
"principal": 0
}, {
"id": 4,
"nome": "A combinar",
"usado": 0,
"visivel": 1,
"principal": 0
}]

Criar métodos de expedição

POST api/1.0/metodos-expedicao

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
nome 1 String (max:30) Qualquer coisa
principal Boolean 0
Response 
  {
  "id": 1238,
  "nome": "Nome Escolhido",
  "usado": 0,
  "visivel": 1,
  "principal": 0
}

Update métodos de expedição

PATCH api/1.0/metodos-expedicao/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
nome String (max:30) Qualquer coisa
visivel Boolean 0
principal Boolean 0
Response 
  {
  "id": 1238,
  "nome": "Nome Escolhido",
  "usado": 0,
  "visivel": 1,
  "principal": 0
}

Delete métodos de expedição

DELETE api/1.0/metodos-expedicao/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
Response 
  #Response status 204

Unidades Medida

Os métodos válidos são:

Todos os items deverão ter uma unidade de medida associada.

Ler Unidades de Medida

GET api/1.0/unidades-medida

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
Response 
  [{
  "id": 1,
  "nome": "Unidade",
  "simbolo": "UN",
  "usado": 0,
  "visivel": 1,
  "principal": 1
}, {
"id": 2,
"nome": "Metro",
"simbolo": "MT",
"usado": 0,
"visivel": 1,
"principal": 0
}, {
"id": 3,
"nome": "Metro Quadrado",
"simbolo": "MT2",
"usado": 0,
"visivel": 1,
"principal": 0
}, {
"id": 4,
"nome": "Metro Cubico",
"simbolo": "MT3",
"usado": 0,
"visivel": 1,
"principal": 0
}, {
"id": 5,
"nome": "Kilograma",
"simbolo": "KG",
"usado": 0,
"visivel": 1,
"principal": 0
}, {
"id": 6,
"nome": "Milheiro",
"simbolo": "MIL",
"usado": 0,
"visivel": 1,
"principal": 0
}, {
"id": 7,
"nome": "Hora",
"simbolo": "H",
"usado": 0,
"visivel": 1,
"principal": 0
}, {
"id": 8,
"nome": "Minutos",
"simbolo": "MIN",
"usado": 0,
"visivel": 1,
"principal": 0
}, {
"id": 9,
"nome": "Dia",
"simbolo": "DIA",
"usado": 0,
"visivel": 1,
"principal": 0
}, {
"id": 10,
"nome": "Metro",
"simbolo": "MT",
"usado": 0,
"visivel": 1,
"principal": 0
}]

Criar Unidades De Medida

POST api/1.0/unidades-medida

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
nome 1 String (max:30) Milimetro
simbolo 1 String (max:15) ML
principal Boolean 0
Response 
  {
  "id": 35,
  "nome": "Milimetro",
  "simbolo": "ML",
  "usado": 0,
  "visivel": 1,
  "principal": 0
}

Update Unidades De Medida

PATCH api/1.0/unidades-medida/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
nome String (max:30) Milimetros
simbolo String (max:15) ML
visivel Boolean 0
principal Boolean 0
Response 
  {
  "id": 35,
  "nome": "Milimetro",
  "simbolo": "ML",
  "usado": 0,
  "visivel": 1,
  "principal": 0
}

Delete Unidade de Medida

DELETE api/1.0/unidades-medida/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
Response 
  #Response status 204

Viaturas

Os métodos válidos são:

Adicione e faça gestão de viaturas. De modo a associar viaturas a um transporte por exemplo.

Ler Viaturas

GET api/1.0/viaturas

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
Response 
  [{
  "id": 1932,
  "nome": "ferrari",
  "matricula": "11-11-XX",
  "usado": 0,
  "visivel": 1,
  "principal": 0
}]

Criar Viaturas

POST api/1.0/viaturas

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
nome 1 String (max:30) Ford Fiesta
matricula 1 String (max:10) 12-33-GT
principal Boolean 0
Response 
  {
  "id": 1936,
  "nome": "ferrari",
  "matricula": "11-11-XX",
  "usado": 0,
  "visivel": 1,
  "principal": 0
}

Update Viaturas

PATCH api/1.0/viaturas/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
nome String (max:30) Ford Fiesta
matricula String (max:10) 12-33-GT
principal Boolean 0
visivel Boolean 1
Response 
  {
  "id": 1936,
  "nome": "ferrari",
  "matricula": "11-11-XX",
  "usado": 0,
  "visivel": 1,
  "principal": 0
}

Delete Viatura

DELETE api/1.0/viaturas/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
Response 
  #Response status 204

Series

Os métodos válidos são:

Adicione e faça gestão das series dos documentos.

Ler Séries

GET api/1.0/series

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
Response 
  [{
  "id": 1,
  "nome": "B2016",
  "iva_incluido": 0,
  "usado": 1,
  "visivel": 1,
  "principal": 1
}]

Criar Series

POST api/1.0/series

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
nome 1 String (Alfa Númerico | max:30 | Único) B2020
iva_incluido Boolean (se verdadeiro nos
documentos as linhas São mostradas
com IVA incluido)		 0
principal Boolean 0
Response 
    {
    "id": 1865,
    "nome": "X2018",
    "iva_incluido": 0,
    "usado": 0,
    "visivel": 1,
    "principal": 0
  }

Update Série

PATCH api/1.0/series/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
nome String (Alfa Númerico | max:30 | Único) B2020
iva_incluido Boolean (se verdadeiro nos
documentos as linhas São mostradas
com IVA incluido)		 0
principal Boolean 0
visivel Boolean 1
Response 
{
    "id": 1865,
    "nome": "X2018",
    "iva_incluido": 1,
    "usado": 0,
    "visivel": 1,
    "principal": 0
  }

Delete Serie

DELETE api/1.0/series/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
Response 
  #Response status 204

Impostos

Os métodos válidos são:

Lista e gestão de impostos. Por defeito a sua conta terá todos os impostos necessários para mercado português. Não sendo necessário adicionar novas taxas de imposto.

Ler Impostos

GET api/1.0/impostos

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
Response 
  [{
  "id": 1,
  "nome": "IVA 23",
  "valor": 23,
  "usado": 0,
  "visivel": 1,
  "principal": 1
}, {
"id": 2,
"nome": "IVA 13",
"valor": 13,
"usado": 0,
"visivel": 1,
"principal": 0
}, {
"id": 3,
"nome": "IVA 6",
"valor": 6,
"usado": 0,
"visivel": 1,
"principal": 0
}, {
"id": 4,
"nome": "IVA 22 - Madeira",
"valor": 22,
"usado": 0,
"visivel": 1,
"principal": 0
}, {
"id": 5,
"nome": "IVA 12 - Madeira",
"valor": 12,
"usado": 0,
"visivel": 1,
"principal": 0
}, {
"id": 6,
"nome": "IVA 5 - Madeira",
"valor": 5,
"usado": 0,
"visivel": 1,
"principal": 0
}, {
"id": 7,
"nome": "IVA 18 - Acores",
"valor": 18,
"usado": 0,
"visivel": 1,
"principal": 0
}, {
"id": 8,
"nome": "IVA 9 - Acores",
"valor": 9,
"usado": 0,
"visivel": 1,
"principal": 0
}, {
"id": 9,
"nome": "IVA 4 - Acores",
"valor": 4,
"usado": 0,
"visivel": 1,
"principal": 0
}]

Criar Imposto

POST api/1.0/impostos

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
nome 1 String (max:30) IVA Novo
valor 1 Integer (min:0 | max:100) 32
principal Boolean 0
Response 
  {
  "id": 1784,
  "nome": "IVA Novo",
  "valor": 10,
  "usado": 0,
  "visivel": 1,
  "principal": 0
}

Update Imposto

PATCH api/1.0/impostos/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
nome String (max:30) IVA Novo
valor Integer (min:0 | max:100) 32
principal Boolean 0
visivel Boolean 1
Response 
  {
  "id": 1784,
  "nome": "IVA Novo",
  "valor": 10,
  "usado": 0,
  "visivel": 0,
  "principal": 0
}

Delete Impostos

DELETE api/1.0/impostos/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
Response 
  #Response status 204

Motivos Isenção

Lista de motivos de isenção que podem ser aplicados nos documentos.

Ler Motivos Isenção

GET api/1.0/motivos-isencao

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
Response 
  [{
  "id": 1,
  "codigo": "M01",
  "motivo": "Artigo 16.\u00ba n.\u00ba 6 al\u00ednea c) do CIVA (Ou similar)"
}, {
"id": 2,
"codigo": "M02",
"motivo": "Artigo 6.\u00ba do Decreto\u2010Lei n.\u00ba 198\/90, de 19 de Junho"
}
]

Lojas / Armazens

Os métodos válidos são:

O Bill conta com uma funcionalidade lojas / armazens. Por defeito todas as contas têm uma loja. É possivel associar documentos, clientes/fornecedores, items a uma ou mais lojas. Isto permite por exemplo colocar um funcionário apenas numa loja e ele poderá apenas ver os items e clientes dessa mesma loja.

Ler Lojas/Armazéns

GET api/1.0/lojas

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
Response 
  [{
  "id": 1,
  "nome": "Loja Principal",
  "principal": 1,
  "usado": 1,
  "visivel": 1,
  "activo": 1,
  "stock_negativo": 1,
  "morada": "",
  "codigo_postal": "",
  "cidade": "",
  "serie_id": null
}, {
"id": 2572,
"nome": "armazem 1",
"principal": 0,
"usado": 0,
"visivel": 1,
"activo": 1,
"stock_negativo": 1,
"morada": "",
"codigo_postal ": "",
"cidade ":"",
"serie_id":null
}]

Criar Loja/Armazem

POST api/1.0/lojas

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
nome 1 String (max:30) IVA Novo
stock_negativo Boolean ( Permite trabalhar com stock negativo ? ) 1
morada String ( 100 ) Rua da saudade
codigo_postal String ( 15 ) 2000-000
cidade String ( 50 ) Porto
morada String ( 100 ) Rua da saudade
serie_id Integer (Poderá associar uma serie a uma loja) 0
Response 
  {
  "id": 2573,
  "nome": "armazem 1",
  "principal": 0,
  "usado": 0,
  "visivel": 1,
  "activo": 1,
  "stock_negativo": 1,
  "morada": "",
  "codigo_postal": "",
  "cidade": "",
  "serie_id": null
}

Update Loja / Armazem

PATCH api/1.0/lojas/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
nome String (max:30) IVA Novo
stock_negativo Boolean ( Permite trabalhar com stock negativo ? ) 1
morada String ( 100 ) Rua da saudade
codigo_postal String ( 15 ) 2000-000
cidade String ( 50 ) Porto
morada String ( 100 ) Rua da saudade
serie_id Integer (Poderá associar uma serie a uma loja) 0
Response 
  {
  "id": 2603,
  "nome": "armazem 2",
  "principal": 0,
  "usado": 0,
  "visivel": 1,
  "activo": 1,
  "stock_negativo": 1,
  "morada": "Rua de Algo",
  "codigo_postal": "2012-323",
  "cidade": "lisboa",
  "serie_id": 1
}

Delete Loja / Armazem

DELETE api/1.0/lojas/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
Response 
  #Response status 204

Contatos

Os métodos válidos são:

No Bill clientes e fornecedores dão pelo nome de contatos.

Ler Contatos

GET api/1.0/contatos

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
page Integer (Pode enviar o número da página) 2
pesquisa[campo] Faz uma pesquisa exacta por valor de um campo. Campos válidos: email, morada, codigo_postal, cidade, pais, site, telefone_contacto, observacoes, prazo_vencimento, retencao, activar_alerta, visivel johndoe@example.com
pesquisa[texto][campo] Faz uma pesquisa do tipo like %valor% por um valor de um campo. Campos válidos: nome, codigo, nif, pessoa_contacto 500000000
Response 
  {
  "total": 2,
  "per_page": 20,
  "current_page": 1,
  "last_page": 1,
  "next_page_url": null,
  "prev_page_url": null,
  "from": 1,
  "to": 2,
  "data": [{
  "id": 1,
  "metodo_expedicao_id": null,
  "metodo_pagamento_id": null,
  "codigo": 282,
  "nome": "Cliente 1",
  "email": "email@exemplo1",
  "morada": "Morada 1",
  "codigo_postal": "2700-323",
  "cidade": "Lisboa",
  "pais": "PT",
  "nif": 9999999990,
  "site": "",
  "pessoa_contacto": "Antonio",
  "telefone_contacto": "21 234 23 23",
  "observacoes": "",
  "prazo_vencimento": 30,
  "retencao": 0,
  "usado": 0,
  "activar_alerta": 0,
  "visivel": 1,
  "alerta_dias_antes": 5,
  "alerta_dias_depois": 5,
  "desconto_padrao": 6,
  "lingua_padrao_documentos": "pt"
}, {
"id": 2,
"metodo_expedicao_id": null,
"metodo_pagamento_id": null,
"codigo": 4554,
"nome": "Cliente 2",
"email": "email@exemplo1",
"morada": "Morada da Saudade",
"codigo_postal": "2232-323",
"cidade": "Lisboa",
"pais": "PT",
"nif": 9999999990,
"site": "",
"pessoa_contacto": "Joaquim",
"telefone_contacto": "21 222 23 23",
"observacoes": "",
"prazo_vencimento": 60,
"retencao": 0,
"usado": 0,
"activar_alerta": 0,
"visivel": 1,
"alerta_dias_antes": 5,
"alerta_dias_depois": 5,
"desconto_padrao": 6,
"lingua_padrao_documentos": "pt"
}]
}

Ler Contato pelo ID

GET api/1.0/contatos/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
Response 
  {
  "id": 1,
  "metodo_expedicao_id": null,
  "metodo_pagamento_id": null,
  "codigo": 282,
  "nome": "Cliente 1",
  "email": "email@exemplo1",
  "morada": "Morada 1",
  "codigo_postal": "2700-323",
  "cidade": "Lisboa",
  "pais": "PT",
  "nif": 9999999990,
  "site": "",
  "pessoa_contacto": "Antonio",
  "telefone_contacto": "21 234 23 23",
  "observacoes": "",
  "prazo_vencimento": 30,
  "retencao": 0,
  "usado": 0,
  "activar_alerta": 0,
  "visivel": 1,
  "alerta_dias_antes": 5,
  "alerta_dias_depois": 5,
  "desconto_padrao": 6,
  "lingua_padrao_documentos": "pt",
  "originario": [],
  "tipo": [{
  "id": 1,
  "nome": "Fornecedor",
  "visivel": 1,
  "pivot": {
  "contato_id": 1,
  "tipo_id": 1
}
}]
}

Criar Contato

POST api/1.0/contatos

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
nome 1 String (max:30) se não souber
o nome poderá colocar
Consumidor Final		 Julio Sousa
pais 1 País em formato ISO 3166-1
alpha-2 (max:2) 		PT
código String (max:30 | Único) 28172272
nif String ( max:15 ) 1
email email ( max:150 ) johndoe@example.com
morada String ( 100 ) Rua da saudade
codigo_postal String ( 15 ) 2000-000
cidade String ( 50 ) Porto
site String (255) http://www.example.com
pessoa_contato String (50) Rua da saudade
telefone_contato String (30) +351 21 282 23 23
observacoes String (250) +351 21 282 23 23
prazo_vencimento Integer (Prazo de Vencimento em dias) 90
retencao Boolean (Faz rentenção a este cliente) 1
retencao Boolean (Faz rentenção a este cliente) 1
activar_alerta Boolean (Gera e-mails de alerta de
faturas a vencer ou vencidas)		 1
visivel Boolean 1
desconto_padrao (min:0, max:100) Integer 5
alerta_dias_antes Integer (min:0, max:365) Quantos dias antes de vencer a fatura lança o aviso 20
alerta_dias_depois Integer (min:0, max:365) Quantos dias depois de vencer a fatura lança o aviso 14
metodo_pagamento_id Integer (Permite adicionar metodo de pagamento por defeito) 17
metodo_expedicao_id Integer (Permite adicionar metodo de expedição por defeito) 28
lingua_padrao_documentos String (2) Pode Ser: pt, fr, ou en pt
lojas Array (array com ids das lojas a que pertence) ['2','12']
tipos Array (array com ids dos tipos a que pertence) ['12','32']
Response 
      {
      "id": 1,
      "metodo_expedicao_id": null,
      "metodo_pagamento_id": null,
      "codigo": 282,
      "nome": "Cliente 1",
      "email": "email@exemplo1",
      "morada": "Morada 1",
      "codigo_postal": "2700-323",
      "cidade": "Lisboa",
      "pais": "PT",
      "nif": 9999999990,
      "site": "",
      "pessoa_contacto": "Antonio",
      "telefone_contacto": "21 234 23 23",
      "observacoes": "",
      "prazo_vencimento": 30,
      "retencao": 0,
      "usado": 0,
      "activar_alerta": 0,
      "visivel": 1,
      "alerta_dias_antes": 5,
      "alerta_dias_depois": 5,
      "desconto_padrao": 6,
      "lingua_padrao_documentos": "pt",
      "originario": [],
      "tipo": [{
      "id": 1,
      "nome": "Fornecedor",
      "visivel": 1,
      "pivot": {
      "contato_id": 1,
      "tipo_id": 1
    }
  }]
}

Update Contato

PATCH api/1.0/contatos/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
nome String (max:30) se não souber
o nome poderá colocar
Consumidor Final		 Julio Sousa
pais País em formato ISO 3166-1
alpha-2 (max:2) 		PT
código String (max:30 | Único) 28172272
nif String ( max:15 ) 1
email email ( max:150 ) johndoe@example.com
morada String ( 100 ) Rua da saudade
codigo_postal String ( 15 ) 2000-000
cidade String ( 50 ) Porto
site String (255) http://www.example.com
pessoa_contato String (50) Rua da saudade
telefone_contato String (30) +351 21 282 23 23
observacoes String (250) +351 21 282 23 23
prazo_vencimento Integer (Prazo de Vencimento em dias) 90
retencao Boolean (Faz rentenção a este cliente) 1
retencao Boolean (Faz rentenção a este cliente) 1
activar_alerta Boolean (Gera e-mails de alerta de
faturas a vencer ou vencidas)		 1
visivel Boolean 1
desconto_padrao (min:0, max:100) Integer 5
alerta_dias_antes Integer (min:0, max:365) Quantos dias antes de vencer a fatura lança o aviso 20
alerta_dias_depois Integer (min:0, max:365) Quantos dias depois de vencer a fatura lança o aviso 14
metodo_pagamento_id Integer (Permite adicionar metodo de pagamento por defeito) 17
metodo_expedicao_id Integer (Permite adicionar metodo de expedição por defeito) 28
lingua_padrao_documentos String (2) Pode Ser: pt, fr, ou en pt
lojas Array (array com ids das lojas a que pertence) ['2','12']
tipos Array (array com ids dos tipos a que pertence) ['12','32']
Response 
    {
    "id": 1,
    "metodo_expedicao_id": null,
    "metodo_pagamento_id": null,
    "codigo": 282,
    "nome": "Cliente 1",
    "email": "email@exemplo1",
    "morada": "Morada 1",
    "codigo_postal": "2700-323",
    "cidade": "Lisboa",
    "pais": "PT",
    "nif": 9999999990,
    "site": "",
    "pessoa_contacto": "Antonio",
    "telefone_contacto": "21 234 23 23",
    "observacoes": "",
    "prazo_vencimento": 30,
    "retencao": 0,
    "usado": 0,
    "activar_alerta": 0,
    "visivel": 1,
    "alerta_dias_antes": 5,
    "alerta_dias_depois": 5,
    "desconto_padrao": 6,
    "lingua_padrao_documentos": "pt",
    "originario": [],
    "tipo": [{
    "id": 1,
    "nome": "Fornecedor",
    "visivel": 1,
    "pivot": {
    "contato_id": 1,
    "tipo_id": 1
  }
}]
}

Delete Contatos

DELETE api/1.0/contatos/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
Response 
  #Response status 204

Items

Os métodos válidos são:

Faça gestão de leitura dos seus items.

Ler Items

GET api/1.0/items

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
page Integer (Pode enviar o número da página) 2
pesquisa[campo] Faz uma pesquisa exacta por valor de um campo. Campos válidos: unidade_medida_id, ProductCategory, visivel, movimenta_stock, imposto_id, preco_custo, servico 1
pesquisa[texto][campo] Faz uma pesquisa do tipo like %valor% por um valor de um campo. Campos válidos: codigo, codigo_barras, descricao Cadeira
Response 
  {
  "total": 3,
  "per_page": 20,
  "current_page": 1,
  "last_page": 1,
  "next_page_url": null,
  "prev_page_url": null,
  "from": 1,
  "to": 3,
  "data": [{
  "id": 1,
  "codigo": 123,
  "codigo_barras": 123,
  "descricao": "Produto 1",
  "imposto_id": 1,
  "unidade_medida_id": 1,
  "ProductCategory": "M",
  "preco_custo": 3,
  "visivel": 1,
  "usado": 0,
  "servico": 0,
  "movimenta_stock": 1,
  "observacoes": "",
  "iva_compra": null,
  "precos": []
}, {
"id": 2,
"codigo": 1234,
"codigo_barras": 1234,
"descricao": "Servico 1",
"imposto_id": 1,
"unidade_medida_id": 1,
"ProductCategory": "M",
"preco_custo": 3,
"visivel": 1,
"usado": 0,
"servico": 1,
"movimenta_stock": 1,
"observacoes": "",
"iva_compra": null,
"precos": []
}, {
"id": 1488,
"codigo": 8821456469,
"codigo_barras": "",
"descricao": "Produto Novo",
"imposto_id": 1,
"unidade_medida_id": 1,
"ProductCategory": "M",
"preco_custo": 0,
"visivel": 1,
"usado": 0,
"servico": 0,
"movimenta_stock": 0,
"observacoes": "",
"iva_compra": 1,
"precos": []
}]
}

Ver Item pelo ID

GET api/1.0/items/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
Response 
  {
  "id": 1,
  "codigo": 123,
  "codigo_barras": 123,
  "descricao": "Produto 1",
  "imposto_id": 1,
  "unidade_medida_id": 1,
  "ProductCategory": "M",
  "preco_custo": 3,
  "visivel": 1,
  "usado": 0,
  "servico": 0,
  "movimenta_stock": 1,
  "observacoes": "",
  "iva_compra": null,
  "categorias": [],
  "unidade_medida": {
  "id": 1,
  "nome": "Unidade",
  "simbolo": "UN",
  "usado": 0,
  "visivel": 1,
  "principal": 1
},
"imposto": {
"id": 1,
"nome": "IVA 23",
"valor": 23,
"usado": 0,
"visivel": 1,
"principal": 1
},
"originario": [],
"precos": []
}

Criar Item

POST api/1.0/items

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
descricao 1 String (max:200) Cadeira de Pinho
codigo 1 String (max:30) 2828211811-A
unidade_medida_id 1 Integer (Id da Unidade de medida) 12
imposto_id 1 Integer (id do imposto) 1
iva_compra 1 Integer (id do imposto de compra) 1
codigo_barras String (max:100) 111291j181j1222sj22
ProductCategory String (1) Pode ser:M,P,A,S,T 1
observacoes Text Verificar se ....
visivel Boolean 1
movimenta_stock Boolean 1
servico Boolean (Se for um serviço colocar true) 0
preco_custo Numeric 12.30
lojas Array (array com ids das lojas a que pertence) ['2','12']
categorias Array (array com ids das categorias a que pertence) ['12','32']
precos array (Um conjunto de precos, cada preco tem 3 argumentos) precos[0][preco_nome]=Preço 1
precos[0][preco_sem_iva]=12.20
precos[0][preco_com_iva]=15.20
Response 
    {
    "id": 1489,
    "codigo": 7567740125,
    "codigo_barras": "",
    "descricao": "Produto Novo",
    "imposto_id": 1,
    "unidade_medida_id": 1,
    "ProductCategory": "M",
    "preco_custo": 0,
    "visivel": 1,
    "usado": 0,
    "servico": 0,
    "movimenta_stock": 0,
    "observacoes": "",
    "iva_compra": 1,
    "categorias": [],
    "originario": [],
    "precos": []
  }

Update Item

PATCH api/1.0/items/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
descricao String (max:200) Cadeira de Pinho
codigo String (max:30) 2828211811-A
unidade_medida_id Integer (Id da Unidade de medida) 12
imposto_id Integer (id do imposto) 1
iva_compra Integer (id do imposto de compra) 1
codigo_barras String (max:100) 111291j181j1222sj22
ProductCategory String (1) Pode ser:M,P,A,S,T 1
observacoes Text Verificar se ....
visivel Boolean 1
movimenta_stock Boolean 1
servico Boolean (Se for um serviço colocar true) 0
preco_custo Numeric 12.30
lojas Array (array com ids das lojas a que pertence) ['2','12']
categorias Array (array com ids das categorias a que pertence) ['12','32']
precos array (Um conjunto de precos, cada preco tem 3 argumentos) precos[0][preco_nome]=Preço 1
precos[0][preco_sem_iva]=12.20
precos[0][preco_com_iva]=15.20
Response 
    {
    "id": 1489,
    "codigo": 7567740125,
    "codigo_barras": "",
    "descricao": "Produto Novo",
    "imposto_id": 1,
    "unidade_medida_id": 1,
    "ProductCategory": "M",
    "preco_custo": 0,
    "visivel": 1,
    "usado": 0,
    "servico": 0,
    "movimenta_stock": 0,
    "observacoes": "",
    "iva_compra": 1,
    "categorias": [],
    "originario": [],
    "precos": []
  }

Delete Item

DELETE api/1.0/items/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
Response 
  #Response status 204

Documentos

São possiveis os seguintes pedidos:

Ler Documentos

GET api/1.0/documentos

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
page Integer (Pode enviar o número da página) 2
pesquisa[campo] Faz uma pesquisa exacta por valor de um campo. Campos válidos: tipo_documento_id, contato_id, terminado, metodo_pagamento_id, serie_id, loja_id, modulo_estado_id, estado johndoe@example.com
pesquisa[texto][campo] Faz uma pesquisa do tipo like %valor% por um valor de um campo. Campos válidos: viatura, invoice_number 500000000
pesquisa[order_by][campo] Permite ordenar os resultados de pesquisa por um campo. Campos válidos: invoice_number, contatos.nome, invoice_date, prazo_vencimento, gross_total, codigo_at, system_entry_date pesquisa[order_by][system_entry_date]=desc
Response 
  {
  "total": 1,
  "per_page": 20,
  "current_page": 1,
  "last_page": 1,
  "next_page_url": null,
  "prev_page_url": null,
  "from": 1,
  "to": 1,
  "data": [{
  "id": 3363,
  "modulo_estado_id": null,
  "loja_id": 1,
  "contato_id": 1,
  "invoice_number": "FT B2016\/1",
  "codigo_at": "",
  "invoice_date": "2017-08-12",
  "gross_total": "2.74",
  "prazo_vencimento": "2017-08-12",
  "terminado": 1,
  "estado": "N",
  "impresso": 0,
  "token_download": "37fea02190633e0a241cd0f5a0b24fa292fa2f3d"
}]
}

Abrir Documento Pelo ID

GET api/1.0/documentos/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
Response 
  {"id":3403,"estado":"N","tipo_documento_id":1,"user_id":1,"contato_id":1,"serie_id":1,"metodo_expedicao_id":1,"metodo_pagamento_id":1,"loja_id":1,"prazo_vencimento":"2017-08-15","viatura":"","observacoes":"","motivo":"","moeda":"","cambio":"0.0000","invoice_number":"FT B2016\/1","invoice_date":"2017-08-15","system_entry_date":"2017-08-15T09:45:04","status_date":"2017-08-15T09:45:04","impresso":0,"data_carga":null,"carga_morada":"","carga_cidade":"","carga_codigo_postal":"","carga_pais":"","data_descarga":null,"descarga_morada":"","descarga_cidade":"","descarga_codigo_postal":"","descarga_pais":"","arredondamento":"0.0000","net_total":"2.23","tax_total":"0.51","gross_total":"2.74","desconto_total":"0.00","retencao_total":"0.00","comunicado":0,"codigo_at":"","terminado":1,"modulo_estado_id":null,"nota_documento":"","lingua":"pt","token_download":"a93fd328e7b06afa36e280d5a35dc5d50b8ffd72","loja":{"id":1,"nome":"Loja Principal","principal":1,"usado":1,"visivel":1,"activo":1,"stock_negativo":1,"morada":"","codigo_postal":"","cidade":"","serie_id":null},"contato":{"id":1,"contato_id":1,"nif":"9999999990","codigo":"282","nome":"Cliente 1","morada":"Morada 1","codigo_postal":"2700-323","cidade":"Lisboa","pais":"PT","retencao":0,"origem":{"id":1,"metodo_expedicao_id":null,"metodo_pagamento_id":null,"codigo":"282","nome":"Cliente 1","email":"email@exemplo1","morada":"Morada 1","codigo_postal":"2700-323","cidade":"Lisboa","pais":"PT","nif":"9999999990","site":"","pessoa_contacto":"Antonio","telefone_contacto":"21 234 23 23","observacoes":"","prazo_vencimento":30,"retencao":0,"usado":1,"activar_alerta":0,"visivel":1,"alerta_dias_antes":5,"alerta_dias_depois":5,"desconto_padrao":6,"lingua_padrao_documentos":"pt"}},"modulo_estado":null,"lancamentos":[{"id":3234,"documento_id":3403,"user_id":1,"item_id":1,"imposto_id":1,"motivo_isencao_id":null,"lancamento_pai_id":null,"loja_id":1,"nome":"Coca cola","referencia_manual":null,"quantidade":"1.0000000000","preco_unitario":"2.2300000000","desconto_1":"0.00000","desconto_2":"0.00000","desconto_3":"0.00000","net_total":"2.23","tax_total":"0.51","gross_total":"2.74","desconto_total":"0.00","retencao_total":"0.00","origem":null,"item":{"id":1,"codigo":"123","codigo_barras":"123","descricao":"Produto 1","imposto_id":1,"unidade_medida_id":1,"ProductCategory":"M","preco_custo":3,"visivel":1,"usado":1,"servico":0,"movimenta_stock":1,"observacoes":"","iva_compra":null,"unidade_medida":{"id":1,"nome":"Unidade","simbolo":"UN","usado":1,"visivel":1,"principal":1}}}],"divida":{"id":2319,"documento_id":3403,"total_divida":"2.74","data_finalizado":null},"pagou":[{"id":2319,"documento_id":3403,"documento_relacionado_id":null,"total":"2.74","documento_relacionado":null}]}

Fazer Download Documento

Nota: O caminho de download do PDF é exterior à nossa API. Não sendo necessário enviar qualquer token.

Nota 2: Por insistencia da autoridade tributária o documento apenas será original no primeiro download. O segundo e posteriores downloads terão a informação de segunda via. Assim sendo, para verificar se o documento se encontra correcto é aconselhavel utilizar a opção de abrir o documento pelo seu ID e não a opção de download do documento.

GET /documentos/download/ID_DO_DOCUMENTO/TOKEN_DOWNLOAD

Criar Documento

POST api/1.0/documentos

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 2 Integer - Se estiver a editar um rascunho deverá enviar o ID do documento. Tenha em atenção que quando um rascunho é editado o seu ID muda, sendo criado um novo ID para este mesmo documento. 1
tipo_documento_id 2 Integer - Deverá
Enviar tipo_documento_id
ou a tipificação		 1
tipificacao 2 String (4) deve ser um destes:
FT, FR ....		 FT
contato_id 2 Integer - Não é obrigatorio. Poderá enviar um array contato e o contato será criado. Caso envie um código de contato ou NIF que já existe na sua conta esse contato será automaticamente associado. Se não enviar nenhum dos dois e enviar apenas o array vazio o documento será associado ao consumidor final. 15
contato 2 array (é opcional, se enviar o contato_id não precisa enviar isto. È útil quando deseja criar um contato no acto de criação do documento.) Array
Nome Tipo Example
nome String Max:150 John Doe
email String Max:150 johndoe@example.com
nif String Max:15 (se for Português deve ser válido) 123456789
codigo String Max:30 Unico AB2718
morada String Max:100 Rua de Algo n15 3b
codigo_postal String Max:15 2999-000
cidade String Max:50 Aveiro
pais String Max:2 PT
site String Max:255 http://www.example.com
telefone_contacto String Max:50 9138728232
produtos 1 Array (poderá ter dentro dele vários Arrays) Sendo cada um deles uma linha do documento. Array
Nome Tipo Example
item_id 2 Integer - é opcional se não enviar item_id e se não enviar codigo ou um código inexistente,
o item será tratado como um item novo e será adicionado na base de dados. 		30
codigo 2 String Max:30 ABCEH212
nome 1 String Max:200 (descriçao do item) Cadeira XPTO - Azul #21
unidade_medida_id 2 Integer - Apenas deverá enviar este valor se o item não existir na base de dados. Caso contrário será ignorado. 2
ProductCategory 2 String (max:1) - Pode ser: M,P,A,S,T Apenas deverá enviar este valor se o item não existir na base de dados. Caso contrário será ignorado. 2
movimenta_stock 2 Boolean Apenas deverá enviar este valor se o item não existir na base de dados. Caso contrário será ignorado. 2
servico 2 Boolean - Se for um serviço Apenas deverá enviar este valor se o item não existir na base de dados. Caso contrário será ignorado. 2
quantidade 1 Float (min:0.00001) 12
preco_unitario 1 Float (min:0) (sempre em euros ainda que o documento seja em moeda estrangeira). 12.00
imposto_id 2 Integer - opcional Poderá enviar o imposto_id ou imposto. Caso o produto esteja isento de imposto poderá enviar este valor a 0 ou imposto a 0. 128
imposto 2 Integer - opcional (Min:0 Max:100)
Poderá enviar o valor da taxa de IVA caso não deseje enviar o imposto_id.Se o IVA que enviar não for um valor válido será aplicada a taxa por defeito.
Se o produto tiver isenção poderá enviar este valor a zero.		 23
isencao 2 String (Max:3) Se enviar o imposto a 0 ou o imposto_id a 0 deverá fazer referência ao código do motivo de isenção.
Por favor veja a tabela dos códigos de motivo de isenção.		 M01
desconto_1 Integer (min:0,Max:100) 5
desconto_2 Integer (min:0,Max:100) 6
desconto_3 Integer (min:0,Max:100) 15
retencao Integer (min:0,Max:100) Poderá ter Retenção na fonte. Deverá enviar a taxa. 11.5
lancamento_pai_id 2 Integer - Opcional: Poderá fazer referencia ao lançamento de outro documento. Relembre-se que este ID é o ID do lançamento originario e não o ID
do documento. Exemplo: Criou uma guia de transporte, e agora está a fazer a fatura da mesma. Poderá referencia a linha dessa guia que dá origem a esta guia.
Outro exemplo é na criação de notas de crédito. É obrigatorio por lei fazer referencia em cada linha ao documento ou a linha
original pois uma nota de crédito é um documento retificativo. Se quiser emitir uma nota de crédito de
um documento criado por outro software poderá usar o campo referencia_manual. 		13822
referencia_manual 2 String - Se por algum motivo deseja emitir uma nota de crédito referente a um documento externo, ou se simplesmente quer referencia
um documento de origem numa fatura. Sempre que necessite fazer uma refência e se possivel tente usar o lancamento_pai_id
para fazer referência ao lancamento original.		 FT A282/182822
loja_id Integer - Se não enviado será usada a loja associada ao utilizador. Se não existir nenhuma será usada a loja por defeito. 18
serie_id Integer - Se não enviado será usada a serie por defeito da loja escolhida. 12
metodo_pagamento_id Integer - Se não enviado será usado o Método de pagamento associado ao cliente por defeito. Se não existir será utilizado o método de pagamento por defeito da empresa. 32
metodo_expedicao_id Integer - Se não enviado será usado o Método de expedição associado ao cliente por defeito. Se não existir será utilizado o método de expedição por defeito da empresa. 23
data Data no Formato: Y-m-d H:i:s se não enviado será utilizada a data e hora de Portugal continental no momento. 2017-08-12 10:32:23
prazo_vencimento Data no Formato: Y-m-d H:i:s se não enviado será utilizada a data e hora somando os dias de vencimento associados ou cliente ou caso não exista os dias de vencimento configurados na ficha da empresa. 2017-08-12 10:32:23
morada String Max:100 Opcional: se desejar faturar com dados diferentes dos da sede do cliente. Rua de Algo n15 3b
codigo_postal String Max:15 Opcional: se desejar faturar com dados diferentes dos da sede do cliente. 2999-000
cidade String Max:50 Opcional: se desejar faturar com dados diferentes dos da sede do cliente. Aveiro
pais String Max:2 Opcional: se desejar faturar com dados diferentes dos da sede do cliente. PT
carga_morada String Max:100 Opcional: Apenas obrigatorio em documentos de transporte Rua de Algo n15 3b
carga_codigo_postal String Max:15 Opcional: Apenas obrigatorio em documentos de transporte 2999-000
carga_cidade String Max:50 Opcional: Apenas obrigatorio em documentos de transporte Aveiro
carga_pais String Max:2 Opcional: Apenas obrigatorio em documentos de transporte PT
data_carga Data no Formato: Y-m-d H:i:s (na criaçao de documentos de transporte a data de carga e descarga são dados obrigatórios deverá enviar data_carga, data_descarga e data do documento) 2017-08-12 10:32:23
descarga_morada String Max:100 Opcional: Apenas obrigatorio em documentos de transporte Rua de Algo n15 3b
descarga_codigo_postal String Max:15 Opcional: Apenas obrigatorio em documentos de transporte 2999-000
descarga_cidade String Max:50 Opcional: Apenas obrigatorio em documentos de transporte Aveiro
descarga_pais String Max:2 Opcional: Apenas obrigatorio em documentos de transporte PT
data_descarga Data no Formato: Y-m-d H:i:s (na criaçao de documentos de transporte a data de carga e descarga são dados obrigatórios deverá enviar data_carga, data_descarga e data do documento) 2017-08-12 10:32:23
viatura String max:20 - (documentos de transporte devem ter a matricula da viatura para serem válidos) XX-28-12
moeda String (max:3) Formato:ISO 4217 http://www.xe.com/iso4217.php. Todos os documentos são criados em EURO, no entanto pode fazer referência ao valor em moeda estrangeira no fim do documento. USD
cambio 2 Float - Valor de cambio face ao EURO. Apenas obrigatório se o documento fizer referência a moeda estrangeira. 1.21
observacoes String (max:200) - Aparece no fim do documento. O cliente deseja que seja entregue a fatura no piso 1.
nota_documento String (Text) - nota interna não visivel no documento. Lorem ipsum dolor sit amet, consectetur adipisicing elit. Debitis illo aspernatur, iure, veritatis minus molestiae!
modulo_estado_id Integer - Poderá atribuir um estado a este documento. 2
lingua String (max:2) - O bill permite que as faturas sejam emitidas em 3 linguas. Português, Francês e Inglês. É aceite então um dos seguintes valores : pt, fr, en fr
arredondamento Float: min:-0.03|max:0.03 - Por lei é possivel aplicar um arredondamento manual ao total de um documento. Sendo este arredondamento positivo ou negativo um valor máximo de 3 centimos. -0.01
terminado boolean - Se deseja terminar o documento envie true ou 1. Caso contrário o documento será gravado como rascunho. 1
Response 
      {
      "id": 3397,
      "estado": "N",
      "tipo_documento_id": 1,
      "user_id": 1,
      "contato_id": 1,
      "serie_id": 1,
      "metodo_expedicao_id": 1,
      "metodo_pagamento_id": 1,
      "loja_id": 1,
      "prazo_vencimento": "2017-08-15",
      "viatura": "",
      "observacoes": "",
      "motivo": "",
      "moeda": "",
      "cambio": "0.0000",
      "invoice_number": "FT B2016\/1",
      "invoice_date": "2017-08-15",
      "system_entry_date": "2017-08-15T09:02:59",
      "status_date": "2017-08-15T09:02:59",
      "impresso": 0,
      "data_carga": null,
      "carga_morada": "",
      "carga_cidade": "",
      "carga_codigo_postal": "",
      "carga_pais": "",
      "data_descarga": null,
      "descarga_morada": "",
      "descarga_cidade": "",
      "descarga_codigo_postal": "",
      "descarga_pais": "",
      "arredondamento": "0.0000",
      "net_total": "2.23",
      "tax_total": "0.51",
      "gross_total": "2.74",
      "desconto_total": "0.00",
      "retencao_total": "0.00",
      "comunicado": 0,
      "codigo_at": "",
      "terminado": 1,
      "modulo_estado_id": null,
      "nota_documento": "",
      "lingua": "pt",
      "token_download": "27f4bb6a55d4f539b40ef455ed7d651b9d4579cb",
      "contato": {
      "id": 1,
      "contato_id": 1,
      "nif": "9999999990",
      "codigo": "282",
      "nome": "Cliente 1",
      "morada": "Morada 1",
      "codigo_postal": "2700-323",
      "cidade": "Lisboa",
      "pais": "PT",
      "retencao": 0
    },
    "lancamentos": [{
    "id": 3228,
    "documento_id": 3397,
    "user_id": 1,
    "item_id": 1,
    "imposto_id": 1,
    "motivo_isencao_id": null,
    "lancamento_pai_id": null,
    "loja_id": 1,
    "nome": "Coca cola",
    "referencia_manual": null,
    "quantidade": "1.0000000000",
    "preco_unitario": "2.2300000000",
    "desconto_1": "0.00000",
    "desconto_2": "0.00000",
    "desconto_3": "0.00000",
    "net_total": "2.23",
    "tax_total": "0.51",
    "gross_total": "2.74",
    "desconto_total": "0.00",
    "retencao_total": "0.00",
    "item": {
    "id": 1,
    "codigo": "123",
    "codigo_barras": "123",
    "descricao": "Produto 1",
    "imposto_id": 1,
    "unidade_medida_id": 1,
    "ProductCategory": "M",
    "preco_custo": 3,
    "visivel": 1,
    "usado": 1,
    "servico": 0,
    "movimenta_stock": 1,
    "observacoes": "",
    "iva_compra": null
  }
}]
}

Anular Documento

PATCH api/1.0/documentos

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer - ID do documento 12
motivo_anular 1 String (max:200) por lei é obrigado a especificar o motivo pelo qual irá anular o documento. Um erro no preço do produto.
data Data no Formato: Y-m-d H:i:s se não enviado será utilizada a data e hora de Portugal continental no momento. 2017-08-12 10:32:23
Response 
  {"id":3410,"estado":"A"}

Apagar Documento

Apenas é possivel em rascunhos.

DELETE api/1.0/documentos/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer 12
Response 
  #Response status 204

Documento Saldo Inicial

Permite registar uma divida a fornecedor ou uma dívida que o cliente tem para connosco. Este documento não pode ser impresso servido apenas para controlar as dividas anteriores ao sistema.

POST api/1.0/documentos/saldo-inicial

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
contato_id 1 Integer - ID do contato 12
serie_id Integer - Se não enviado será usada a serie por defeito da loja escolhida. 12
observacoes String (max:200) Divida referente ao periodo de X a Y.
data Data no Formato: Y-m-d H:i:s se não enviado será utilizada a data e hora de Portugal continental no momento. 2017-08-12 10:32:23
prazo_vencimento Data no Formato: Y-m-d H:i:s se não enviado será utilizada a data e hora de Portugal continental no momento. 2017-08-12 10:32:23
prazo_vencimento Data no Formato: Y-m-d H:i:s se não enviado será utilizada a data e hora de Portugal continental no momento. 2017-08-12 10:32:23
tipo_documento_id Integer - Apenas são aceites os valores: 26 ou 27 Sendo : Saldo de Cliente e Saldo a Fornecedor respectivamente. 26
metodo_pagamento_id Integer - Se não enviado será usado o Método de pagamento associado ao cliente por defeito. Se não existir será utilizado o método de pagamento por defeito da empresa. 32
net_total 1 Float - Valor Divida sem IVA 12.28
gross_total 1 Float - Valor Divida com IVA 17.28
Response 
  {"observacoes":"Divida referente ao periodo a anterior a ...","invoice_date":"2017-08-15","prazo_vencimento":"2017-08-15 10:14:25","system_entry_date":"2017-08-15T10:14:25","status_date":"2017-08-15T10:14:25","cambio":1,"moeda":"EUR_\u20ac","serie_id":1,"terminado":true,"serie_counter":1,"contato_id":1,"metodo_pagamento_id":1,"contato_header_id":1,"empresa_header_id":1,"tipo_documento_id":26,"gross_total":45,"net_total":30,"user_id":1,"id":3420,"invoice_number":"SINIV B2016\/1","serie":{"id":1,"nome":"B2016","iva_incluido":0,"usado":1,"visivel":1,"principal":1},"tipo_documento":{"id":26,"tipificacao":"SINIV","nome":"Saldo Cliente","categoria":"faturas","movimento":"saida","movimento_contabilistico":"credito","certificado":0,"movimenta_stock":0,"gera_pendentes":0,"regulariza_pendentes":0,"gera_divida":1,"auto_liquidacao":0,"menu_destacado":1}}

Comunicar Guia

Para que a guia seja comunicada deverá ter os dados do utilizador da autoridade tributária correctamente configurados nas configurações da empresa. Os webservices da autoridade tributária não se encontram funcionais 100% do tempo. Em alguns casos poderá ter de voltar a tentar a comunicação. Caso não seja possivel a mesma ser feita poderá comunicar utilizando o website da AT e colocar o código atribuido à guia manualmente.

POST api/1.0/documentos/comunicar/guia/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer - ID deverá ir no URL 12
Response 
  {"resultado":"...","codigo_at":"328282772"}

Adicionar código AT Manualmente

Os webservices da autoridade tributária não se encontram funcionais 100% do tempo. Caso não seja possivel a mesma ser feita poderá comunicar utilizando o website da AT e colocar o código atribuido à guia manualmente.

POST api/1.0/documentos/adicionar/codigo-at

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer - ID do documento 12
codigo_at 1 O código que deseja adicionar à guia 28283723
Response 
  {"id":3442,"invoice_number":"FT B2016\/1","codigo_at":"2181821"}

Enviar Documento por E-mail

Enviar um documento por e-mail.

POST api/1.0/documentos/enviar-por-email

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer - ID do documento 12
email 1 Email johndoe@example.com
Response 
 ["Enviado com sucesso"]

Adicionar nota ao documento

POST api/1.0/documentos/nota-documento

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer - ID do documento 12
nota_documento 1 nota_documento Lorem ipsum dolor sit amet, consectetur adipisicing elit. In accusantium quo aliquam.
At, cum maxime deserunt. Veniam unde quod consequuntur nulla quia,
hic animi sunt ullam perferendis doloremque nihil repudiandae.
Response 
  {"id":3478,"nota_documento":"Lorem ipsum dolor sit amet, consectetur adipisicing elit. Voluptatum similique in temporibus quasi doloremque ratione, incidunt esse praesentium sit nobis explicabo enim doloribus fugit quae, dolor cupiditate. Eligendi corporis et, voluptatibus consectetur debitis saepe ratione optio quasi est odit tempora accusantium, modi laborum accusamus, fuga, animi! Beatae saepe eveniet dolore."}

Stock

São possiveis os seguintes pedidos:

Ver Stock

GET api/1.0/stock

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
data_stock Data no Formato: Y-m-d H:i:s se não enviado será utilizada a data e hora de Portugal continental no momento. 2017-08-12 10:32:23
lojas Array com IDs se desejar filtrar por lojas [1,32]
itens Array com ID's se desejar filtrar por itens [42,21]
Response 
  {"total":1,"per_page":50,"current_page":1,"last_page":1,"next_page_url":null,"prev_page_url":null,"from":1,"to":1,"data":[{"id":3194,"loja_id":1,"item_id":1,"lancamento_id":3326,"quantidade_saida":1,"quantidade_entrada":0,"stock":-1,"data_movimento":"2017-08-16 03:24:47","microtime":1502853887.8103,"item":{"id":1,"codigo":123,"codigo_barras":123,"descricao":"Produto 1","imposto_id":1,"unidade_medida_id":1,"ProductCategory":"M","preco_custo":3,"visivel":1,"usado":1,"servico":0,"movimenta_stock":1,"observacoes":"","iva_compra":null}}]}

Ver Stock de um item numa loja especifica

Este pedido é ideal para evitar a páginação e aceder rápidamente ao stock disponivel de um produto especifico numa loja especifica. Mas é possivel conseguir a mesma informação com o pedido anterior.

GET api/1.0/stock/singular

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
data_stock Data no Formato: Y-m-d H:i:s se não enviado será utilizada a data e hora de Portugal continental no momento. 2017-08-12 10:32:23
item_id 1 Integer ID do item 222
loja_id 1 Integer ID da loja 86
Response 
  {"id":3206,"empresa_id":1,"loja_id":1,"item_id":1,"lancamento_id":3339,"quantidade_saida":"1.000000","quantidade_entrada":"0.000000","stock":"-1.000000","data_movimento":"2017-08-16 03:31:00","microtime":"1502854260.324000","created_at":"2017-08-16 03:31:00","updated_at":"2017-08-16 03:31:00"}

Ver Movimentos de Stock

GET api/1.0/stock/movimentos

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
data_stock Data no Formato: Y-m-d H:i:s se não enviado será utilizada a data e hora de Portugal continental no momento. 2017-08-12 10:32:23
lojas Array com IDs se desejar filtrar por lojas [1,32]
itens Array com ID's se desejar filtrar por itens [42,21]
Response 
  {"total":1,"per_page":50,"current_page":1,"last_page":1,"next_page_url":null,"prev_page_url":null,"from":1,"to":1,"data":[{"id":3232,"empresa_id":1,"loja_id":1,"item_id":1,"lancamento_id":3366,"quantidade_saida":"1.000000","quantidade_entrada":"0.000000","stock":"-1.000000","data_movimento":"2017-08-16 03:44:08","microtime":"1502855048.291900","created_at":"2017-08-16 03:44:08","updated_at":"2017-08-16 03:44:08"}]}

Movimentos

São possiveis os seguintes pedidos:

Movimentos pendentes de conversão de um contato

Com este pedido poderá ver os documentos que estão com movimentos pendentes de um determinado contacto. Poderá aindar enviar a tipificação do documento que deseja criar e assim ver apenas os documentos que podem ser convertidos por essa tipificação. Exemplo: Se desejar importar lançamentos para uma fatura que vai criar poderá enviar FT. Assim verá todos os movimentos pendentes de orçamentos, guias etc. Se desejar criar uma nota de crédito poderá enviar NC e verá todos os documentos que podem ser convertidos em nota de crédito. Depois poderá utilizar um dos seguintes pedidos para ver os lançamentos de cada um dos documentos.

GET api/1.0/movimentos-pendentes

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
contato_id 1 Integer - para converter um documento lembre-se que
deverá ser do mesmo cliente. Exemplo uma guia de transporte para fatura		 13
tipificacao String (max:3) - Se deseja criar uma Fatura envie a tipificação FT e verá quais os
documentos que podem ser convertidos por fatura que se encontram pendentes.		 NC
Response 
  {"total":1,"per_page":20,"current_page":1,"last_page":1,"next_page_url":null,"prev_page_url":null,"from":1,"to":1,"data":[{"id":3105,"origem":3602,"origem_documento":{"id":3602,"invoice_number":"GT B2016\/1","invoice_date":"2017-08-16","gross_total":"2.74"}}]}

Ver Movimentos Pendentes de multiplos Documentos

GET api/1.0/movimentos-pendentes/multiplos

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Array com IDs dos documentos que deseja ver os lançamentos pendentes [1,32]
Response

Devolve um array. Sendo cada chave o ID de um dos documentos Pesquisados. Por suave vez dentro desse elemento tem mais uma vez um array com os lançamentos pendentes.

  {"3619":[{"id":3119,"origem":3619,"quantidade":"1.00000","quantidade_movida":"0.00000","lancamento_original":{"id":3435,"documento_id":3619,"user_id":1,"empresa_id":1,"item_id":1,"imposto_id":1,"motivo_isencao_id":null,"lancamento_pai_id":null,"loja_id":1,"nome":"Coca cola","referencia_manual":null,"quantidade":"1.0000000000","preco_unitario":"2.2300000000","desconto_1":"0.00000","desconto_2":"0.00000","desconto_3":"0.00000","net_total":"2.23","tax_total":"0.51","gross_total":"2.74","desconto_total":"0.00","retencao_total":"0.00","created_at":"2017-08-16 03:55:33","updated_at":"2017-08-16 03:55:33","imposto":{"id":1,"empresa_id":1,"nome":"IVA 23","valor":23,"usado":1,"visivel":1,"principal":1,"created_at":null,"updated_at":"2017-08-16 03:55:33"},"motivo_isencao":null,"item":{"id":1,"codigo":"123","codigo_barras":"123","descricao":"Produto 1","empresa_id":1,"imposto_id":1,"unidade_medida_id":1,"ProductCategory":"M","preco_custo":3,"visivel":1,"usado":1,"servico":0,"movimenta_stock":1,"created_at":null,"updated_at":"2017-08-16 03:55:33","observacoes":"","iva_compra":null,"unidade_medida":{"id":1,"empresa_id":1,"nome":"Unidade","simbolo":"UN","usado":1,"visivel":1,"principal":1,"created_at":null,"updated_at":"2017-08-16 03:55:33"}}}}]}

Ver movimentos pendentes de um documento pelo ID

GET api/1.0/movimentos-pendentes/ID

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer - Id deve ir no url 53
Response

Devolve um array de lançamentos do respectivo documento pesquisado.

  [{"id":3134,"origem":3637,"quantidade":"1.00000","quantidade_movida":"0.00000","lancamento_original":{"id":3452,"documento_id":3637,"user_id":1,"empresa_id":1,"item_id":1,"imposto_id":1,"motivo_isencao_id":null,"lancamento_pai_id":null,"loja_id":1,"nome":"Coca cola","referencia_manual":null,"quantidade":"1.0000000000","preco_unitario":"2.2300000000","desconto_1":"0.00000","desconto_2":"0.00000","desconto_3":"0.00000","net_total":"2.23","tax_total":"0.51","gross_total":"2.74","desconto_total":"0.00","retencao_total":"0.00","created_at":"2017-08-16 04:35:28","updated_at":"2017-08-16 04:35:28","imposto":{"id":1,"empresa_id":1,"nome":"IVA 23","valor":23,"usado":1,"visivel":1,"principal":1,"created_at":null,"updated_at":"2017-08-16 04:35:28"},"motivo_isencao":null,"item":{"id":1,"codigo":"123","codigo_barras":"123","descricao":"Produto 1","empresa_id":1,"imposto_id":1,"unidade_medida_id":1,"ProductCategory":"M","preco_custo":3,"visivel":1,"usado":1,"servico":0,"movimenta_stock":1,"created_at":null,"updated_at":"2017-08-16 04:35:28","observacoes":"","iva_compra":null,"unidade_medida":{"id":1,"empresa_id":1,"nome":"Unidade","simbolo":"UN","usado":1,"visivel":1,"principal":1,"created_at":null,"updated_at":"2017-08-16 04:35:28"}}}}]

Recibos

São possiveis os seguintes pedidos:

Criar Recibo

POST api/1.0/recibos

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
contato_id 1 Integer 12
tipo_documento_id 1 Integer (poder ser recibo 28, ou recibo a fornecedor 29) 12
documentos 1 Array com info dos documentos que vão ser pagos Array
Nome Tipo Example
documentos[0][documento_id] 1 Integer - ID do documento que estamos a pagar. Uma linha do array por cada documento que será pago neste recibo. 30
documentos[0][total] 1 Float (valor total do pagamento) este valor não deve conter o valor o do desconto. O total abatido no documento será:
total + total_desconto = total_pago
Exemplo: um documento de 50.00€ poderá ser pago na totalidade da seguinte forma:
total = 30.00, total_desconto = 20.00		 30.00
documentos[0][total_desconto] 1 Float (valor total de um desconto) 12.20
data Data no Formato: Y-m-d H:i:s se não enviado será utilizada a data e hora de Portugal continental no momento. 2017-08-12 10:32:23
serie_id Integer - Se não enviado será usada a serie por defeito da loja escolhida. 12
metodo_pagamento_id Integer - Se não enviado será usado o Método de pagamento associado ao cliente por defeito. Se não existir será utilizado o método de pagamento por defeito da empresa. 32
lingua (String max:2) Pode ser pt,en,fr pt
morada (String max:100) Rua da Saudade n25
codigo_postal (String max:15) 1000-000
cidade (String max:50) Porto
pais (String max:2) PT
observacoes (String max:200) Rua da Saudade n25
Response 
          {"observacoes":"","invoice_date":"2017-09-18","system_entry_date":"2017-09-18T11:15:15","status_date":"2017-09-18T11:15:15","cambio":1,"moeda":"EUR","lingua":"pt","serie_id":448,"terminado":true,"serie_counter":1,"contato_id":52,"metodo_pagamento_id":3,"contato_header_id":58,"empresa_header_id":1,"tipo_documento_id":28,"gross_total":2.74,"user_id":1,"id":102,"invoice_number":"RC XXX\/1","net_total":2.23,"tax_total":0.51,"desconto_total":0,"retencao_total":0,"serie":{"id":448,"nome":"XXX","iva_incluido":0,"usado":0,"visivel":1,"principal":1,"cae":""}}

Gerar Recibo Para um Documento Pelo seu ID

POST api/1.0/recibos/pagar/ID_DOCUMENTO

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
Response 
          {"observacoes":"","invoice_date":"2017-09-18","system_entry_date":"2017-09-18T11:16:59","status_date":"2017-09-18T11:16:59","cambio":1,"moeda":"EUR","lingua":"pt","serie_id":448,"terminado":true,"serie_counter":1,"contato_id":88,"metodo_pagamento_id":3,"contato_header_id":98,"empresa_header_id":1,"tipo_documento_id":28,"gross_total":2.74,"user_id":1,"id":176,"invoice_number":"RC XXX\/1","net_total":2.23,"tax_total":0.51,"desconto_total":0,"retencao_total":0,"serie":{"id":448,"nome":"XXX","iva_incluido":0,"usado":0,"visivel":1,"principal":1,"cae":""}}

Autoridade Tributária

São válidos os seguintes pedidos:

Estes pedidos estão relacionados com a comunicação de ficheiros saf-t ou guias à autoridade tributária. Permitem a configuração dos dados do website da AT assim como o teste dos mesmos.

Configurar Username e Password da AT

Permite configurar a password e utilizador da autoridade tributária.

POST api/1.0/at/configurar

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
username_at 1 String (15) 123456789/1
password_at 1 String (25) AEUEHKA828
Response 
          {"success": true}

Teste de Dados

Permite testar os dados para saber se estão ok.

POST api/1.0/at/teste-dados-at

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
Response 
          {"success": "Login feito com sucesso"}

Teste Comunicação Séries

Com este route poderá testar se consegue ou não comunicar séries. Se gerar um erro poderá geralmente indicar uma das seguintes situações: Password do subutilizador incorrecta. Permissões incorrectas.

POST api/1.0/at/teste-comunicacao-series

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
Response 
          // resposta irá mostrar uma lista fazia de séries ou erro 308

Comunicar Série

Permite comunicar uma série.

POST api/1.0/series/comunicar/{id}

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
Response 
          {'result' => 'ok'}

Estado Configuração

Permite testar os dados se os dados definidos ja foram testados ou não e se estão correctos. Sempre que os dados forem actualizados e o login não for testado novamente este valor vai voltar para false.

POST api/1.0/at/estado-configuracao

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
Response 
          {
              "login_at_valido": 0
          }

Ver Opção Envio

Verifica se o saf-t está configurado para enviar automatico

GET api/1.0/empresa/saft-automatico

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
Response 
          {
            "envio_automatico_saft": 1
          }

Configurar Opção Envio

Configurar se o SAF-T É enviado automáticamente.

POST api/1.0/empresa/saft-automatico

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
envio_automatico_saft 1 Boolean 1
Response 
          {
            "envio_automatico_saft": 1
          }

Enviar Saft para E-mail

Permite comunicar uma série.

POST api/1.0/saft/email

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
email 1 E-mail 1
inicio 1 Data YYYY-MM-DD (primeiro dia do mês) 1
fim 1 Data YYYY-MM-DD (fim do mês) 1
fim 1 Data YYYY-MM-DD (fim do mês) 1
tipo 1 mensal 1
Response 
          {'result' => 'ok'}

Comunicar SAF-T

Use se desejar poderá comunicar um SAF-T a qualquer momento.

POST api/1.0/empresa/saft-automatico

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
ano 1 Ano 1
mes 1 Mês 1
Response 
          {
          "id": 13,
          "empresa_id": 1,
          "tipo": "saft",
          "info": "saft 2018\/04",
          "resultado": "file_not_found<\/errors>",
          "sucesso": 0,
          "created_at": "2018-05-05 21:37:01",
          "updated_at": "2018-05-05 21:37:01"
        }

Registo comunicações

Cada comunicação de Guia de Transporte ou ficheiro SAF-T fica registada. Aqui podemos ver as mesmas

POST api/1.0/at/registo-comunicacoes

Parameters
Nome Tipo Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
pesquisa[campo] Faz uma pesquisa exacta por valor de um campo. Campos válidos: tipo, sucesso pesquisa[tipo]=saft
pesquisa[texto][campo] Faz uma pesquisa do tipo like %valor% por um valor de um campo. Campos válidos: info, resultado pesquisa[texto][info]=2018/06
Response 
          {
    "total": 1,
    "per_page": 40,
    "current_page": 1,
    "last_page": 1,
    "next_page_url": null,
    "prev_page_url": null,
    "from": 1,
    "to": 1,
    "data": [
        {
            "id": 13,
            "empresa_id": 1,
            "tipo": "saft",
            "info": "saft 2018/04",
            "resultado": "file_not_found",
            "sucesso": 0,
            "created_at": "2018-05-05 21:37:01",
            "updated_at": "2018-05-05 21:37:01"
        }
    ]
}