🇬🇧 ENGLISH | 🇵🇹 PORTUGUESE

API for Portuguese Billing System - Bill.pt


SDKs to help development and code examples

PHP SDK & examples NODEJS SDK & examples PYTHON SDK & examples

Welcome

Our API allows the integration between our Billing Software and different systems. The API documentation is divided between 4 areas. Our responses are always made in JSON format..

  • Request - Route
  • Parameters - Information that you can send.
    • Field 1 Mandatory
    • Field 2 Can be mandatory (depends on other parameter).
  • Response - Response from the server
  • Error - Error code list.

All requests are done in the following formats:GET POST PATCH DELETE this information is present on each request.

The base API URL for the requests is:
https://app.bill.pt Production
https://dev.bill.pt Test Server

Versions

Current Version is: 1.0

Errors

Errors are returned in the following JSON format: 

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

An object with an array of errors. There may be multiple errors in the response. To interpret the errors you can analyze the following table

3 Kinds of Errrors:

  • 1.password - error_code.name_of_the_field
  • 100.quantidade.1 - error_code.name_of_the_field.value
  • 200 - error_code

Therefore, the first numeric value always indicates the error code. The field name can exist and is always separated from the error code by the character "." This field name may not be displayed in snake_case. So "imposto_id" can appear as "1.imposto id". Finally, also separated by the character "." a value can appear. Analyzing the error code it's also important. Codes 0 through 99 come with code.field_name. Codes 100 through 199 come with code.field_name.value. Code greater than 200 comes with no extra values..

Errors Table
Code Error Description
Código: 0 .. 99
1.field_name The field is mandatory.
2.field_name The field must be an e-mail.
3.field_name The field must be unique. (already exists in the database).
4.field_name The field need confirmation. (field_name_confirmed)
5.field_name The field must be a boolean.
6.field_name The field cannot have special symbols.
7.field_name The field must an integer.
8.field_name The field must be alpha numeric.
9.field_name The value of the field is invalid.
10.field_name The field must be numeric.
Code: 100 .. 199
100.field_name.value The field should have minimum :value characters.
101.field_name.value The field should not have more the then :value characters.
102.field_name.value There is already a document in this serie with a date that is more recent :value
Code: 200+
200 Incorrect login.
201 Was not possible to create the token.
202 No token provided.
203 Session Expired.
204 Is already Active.
205 Invalid User
206 VAT (NIF) invalid.
207 This user don't belongs to this account.
208 Invalid Token.
209 Wrong value.
210 This user don't exists.
211 This user was already used.
212 The user ID is mandatory.
213 You can't edit users..
214 Postal code is in the wrong format. Correct One XXXX-XXX or XXXX.
215 Invalid File.
216 One of the users don't belongs to this account.
217 One of the clients don't belong to this account.
218 One of the products don't belong to this account.
219 This category don't exists.
220 The type don't exists.
221 The unit of measure don't exists.
222 The object you are trying to delete was already used.
223 Payment method don't exists.
224 Shipping method don't exists.
225 The client don't exists.
226 There is already a serie with this name.
227 This serie don't exists.
228 The car don't exists.
229 The Tax don't exists.
230 The product don't exists.
231 The code is not unique.
232 Is not possible to detect the code. The file is invalid.
233 Is not possible to detect the code or NIF. The file is invalid.
234 The file is incorrect. Column productCode not found.
235 You just can delete draft documents.
236 The document already have a payment. It can't be canceled. Cancel the payment first.
237 The document is not from the current month so it can't be canceled.
238 You cannot cancel a document that was created more the 5 days ago.
239 Date of unloading is invalid.
240 Loading date should be after the document date.
241 Due date cannot be previous to the document date.
242 There is a document in the same serie with a date bigger that the one you provide. :valor
243 The document total can't be less then zero.
244 You can't create an invoice with this amount to an anonymous customer.
245 The user don't have permissions.
246 If the document is converted to a corrective document, this document can no longer be canceled. If you wish to make changes to this document, you can issue a debit or credit note associated with this document.
247 The warehouse is incorrect.
248 Invalid Token.
249 Comunication Invalid.
250 You must define your Tax Authority details.
251 The document was already converted by another one. Cancel this other document first.
252 This VAT Number is already in use. We just allow one account per company. If you believe this is a mistake please contact suporte@bill.pt.
253 This vat number already exists in other client.
254 Your plan reach the limit of documents. Please check your plan limits.
255 You reach your plan limit. Please check your plan limit.
256 You reach your plan limit. Please check your plan limit.
257 Your Plan don't allow to manage stock.
258 Your plan don't allow to do this action.
259 You can't use this account.
260 You can't manage orders.
261 You can't manage sales.
262 You can't manage receipts.
263 The state is incorrect.
264 Code is Invalid.
265 You can't work at this time.
266 Credit or Debit Note are documents to rectify invoices. All lines in this document must refer to the original document. One or more lines in this document do don't have reference to the original document.
267 You can't work now.
268 License Already finished.
269 License was already Used.
270 Did not send motivo_isencao (exemption) so you should send imposto or imposto_id (tax).
271 Is not possible to sell a product with price Zero. You must put 100% discount if you want to an offer .
272 The document is not finalized yet.
273 The image must be jpg or jpeg and max size 1200x800.
274 Exemption reason is invalid.
275 You can't use VAT examption in this kind of document. Use regular invoice.
276 Was not possible to communicate the document.
277 Login Failed. Please try your login information in: https://www.acesso.gov.pt/v2/login
288 You can't filter by a shop that don't belongs to this user..
289 The document is already canceled.

How to get an API KEY

In Bill we treat each user independently. Then an account may have 2 users and one of them may not have access to the API.

To generate an api key you can access Bill's account and in the User Management give the user API permission and generate a key for the user.

Now the user will have access to his key when accessing his account settings. You can also access the user's key using the following request.

POST api/1.0/auth/login

Parameters
Field Type 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"
            }

Developers..

Developers who do not have access to an official account should ask support to create a special account so that they can access the API for testing..

Limits

The limits of our api are: 100 requests per minute. To control the limits, 2 headers are provided, returned in each order.

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

In order to make a responsible use of the API it is advisable to keep some data on your side to reduce the number of requests. It is also advised if necessary to synchronize items or contacts in a phased manner.

Types Of Clients (contacts)

In bill there are types of contacts (customers / suppliers). They work as categories to organize your contacts. So you can for example create type "Supplier", "Customer", "Customer Type 2" etc

Get Contact Types

GET api/1.0/tipos

Parameters
Field Type 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"
}]

Create Contact Type

POST api/1.0/tipos

Parameters
Field Type 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 Contact Type

PATCH api/1.0/tipos/ID

Parameters
Field Type 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"
}

Document States

Bill allows you to associate states to documents. This is especially useful if you want to mark an estimate as pending, accepted, delivered etc... you can create as many states as you like and apply to any document.

Get States

GET api/1.0/estados

Parameters
Field Type 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"
  }
]

Create States

POST api/1.0/estados

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
nome 1 String (30) (name) Em espera
principal Boolean (if is the default state) 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 States

PATCH api/1.0/estados/ID

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
nome 1 String (30) Em espera
principal Boolean (if is the main one) 0
visivel Boolean (if is visible) 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"
  }

Delete States

DELETE api/1.0/estados/ID

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
Response 
{}

Change Document State

POST api/1.0/estados

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
documento_id 1 Document ID 133
modulo_estado_id 1 State ID 234
Response 
{}

Document Types

The following requests are valid:

In Bill there are several types of documents, you can get information about the types of documents available and the respective IDs in the following request:

Get Document Types

GET api/1.0/tipos-documento

Parameters
Field Type 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"
}
]

Get Document Types By Category

GET api/1.0/tipos-documento/CATEGORIA

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
categoria 1 String (10) You should put the category in the URL.
Valid options: 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"
}
]

Payment Methods

Information that should be present in the documents. Each payment method has a unique ID associated with it. To find out the payment methods for your account use the following request.

Get Payment Methods

GET api/1.0/metodos-pagamento

Parameters
Field Type 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
}
]

Shipping Methods

The following requests are valid:

Information that should be present in the documents. Each shipping method has a unique ID associated with it. To find out the shipping methods for your account use the following request.

Get Shipping Methods

GET api/1.0/metodos-expedicao

Parameters
Field Type 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
}]

Create Shipping Methods

POST api/1.0/metodos-expedicao

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
nome 1 String (max:30) (name) Qualquer coisa
principal Boolean (if is the default one) 0
Response 
  {
  "id": 1238,
  "nome": "Nome Escolhido",
  "usado": 0,
  "visivel": 1,
  "principal": 0
}

Update Shipping Methods

PATCH api/1.0/metodos-expedicao/ID

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (Should be in the URL) 12
nome String (max:30) (name) Qualquer coisa
visivel Boolean (if is visible) 0
principal Boolean (if is the default) 0
Response 
  {
  "id": 1238,
  "nome": "Nome Escolhido",
  "usado": 0,
  "visivel": 1,
  "principal": 0
}

Delete Shipping Methods

DELETE api/1.0/metodos-expedicao/ID

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

Units of Measure

Valid Requests:

All products must have an associated unit of measure.

Get Units of Measure

GET api/1.0/unidades-medida

Parameters
Field Type 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
}]

Create Units of Measure

POST api/1.0/unidades-medida

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
nome 1 String (max:30) (name) Milimetro
simbolo 1 String (max:15) (symbol example: KG) ML
principal Boolean (if is the default) 0
Response 
  {
  "id": 35,
  "nome": "Milimetro",
  "simbolo": "ML",
  "usado": 0,
  "visivel": 1,
  "principal": 0
}

Update Units of Measure

PATCH api/1.0/unidades-medida/ID

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
nome String (max:30) (name) Milimetros
simbolo String (max:15) (symbol) ML
visivel Boolean (if is visible) 0
principal Boolean (if is the default) 0
Response 
  {
  "id": 35,
  "nome": "Milimetro",
  "simbolo": "ML",
  "usado": 0,
  "visivel": 1,
  "principal": 0
}

Delete Units of Measure

DELETE api/1.0/unidades-medida/ID

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

Vehicles

Valid Requests:

Add and manage vehicles. In order to associate vehicles with a transport for example..

Get Vehicles

GET api/1.0/viaturas

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

Create Vehicles

POST api/1.0/viaturas

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
nome 1 String (max:30) (name) Ford Fiesta
matricula 1 String (max:10) (license plate) 12-33-GT
principal Boolean (is the default?) 0
Response 
  {
  "id": 1936,
  "nome": "ferrari",
  "matricula": "11-11-XX",
  "usado": 0,
  "visivel": 1,
  "principal": 0
}

Update Vehicles

PATCH api/1.0/viaturas/ID

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

Delete Vehicles

DELETE api/1.0/viaturas/ID

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

Series

Valid Requests:

Add and manage the series.

GET Series

GET api/1.0/series

Parameters
Field Type 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
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
nome 1 String (Alpha Numeric | max:30 | Unique) B2020
iva_incluido Boolean (If true
prices in document will
include taxes)		 0
principal Boolean (if is the default) 0
Response 
    {
    "id": 1865,
    "nome": "X2018",
    "iva_incluido": 0,
    "usado": 0,
    "visivel": 1,
    "principal": 0
  }

Update Serie

PATCH api/1.0/series/ID

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
nome String (Alpha Númerico | max:30 | unique) B2020
iva_incluido Boolean (If true
prices will show
with taxes included)		 0
principal Boolean (if is the default?) 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
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
Response 
  #Response status 204

Taxes

Valid Methods:

By default, your account will have all the necessary taxes for the Portuguese market. No need to add new tax rates.

Get Taxes

GET api/1.0/impostos

Parameters
Field Type 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
}]

Create Taxes

POST api/1.0/impostos

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
nome 1 String (max:30) (name) IVA Novo
valor 1 Integer (min:0 | max:100) % value 32
principal Boolean (is the default?) 0
Response 
  {
  "id": 1784,
  "nome": "IVA Novo",
  "valor": 10,
  "usado": 0,
  "visivel": 1,
  "principal": 0
}

Update Taxes

PATCH api/1.0/impostos/ID

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
nome String (max:30) Name IVA Novo
valor Integer (min:0 | max:100) % value 32
principal Boolean (is the default?) 0
visivel Boolean (is visible?) 1
Response 
  {
  "id": 1784,
  "nome": "IVA Novo",
  "valor": 10,
  "usado": 0,
  "visivel": 0,
  "principal": 0
}

Delete Taxes

DELETE api/1.0/impostos/ID

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

Exemption Reasons

List of exemption reasons that can be applied to documents

Get Exemption Reasons

GET api/1.0/motivos-isencao

Parameters
Field Type 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"
}
]

Shops / Warehouses

Os métodos válidos são:

Bill has a store / warehouse feature. By default, all accounts have a store. It is possible to associate documents, customers / suppliers, items with one or more stores. This allows, for example, to add an employee only in one store and he will only be able to see the items and customers of that same store.

Get Shops / Warehouses

GET api/1.0/lojas

Parameters
Field Type 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
}]

Create Shops / Warehouses

POST api/1.0/lojas

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
nome 1 String (max:30) name IVA Novo
stock_negativo Boolean ( Allow negative stock ? ) 1
morada String ( 100 ) Address Rua da saudade
codigo_postal String ( 15 ) Postal Code 2000-000
cidade String ( 50 ) City Porto
serie_id Integer (Associate a Serie with a shop) 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 Shops / Warehouses

PATCH api/1.0/lojas/ID

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
nome String (max:30) (name) IVA Novo
stock_negativo Boolean ( Can work with negative stock? ) 1
morada String ( 100 ) (address) Rua da saudade
codigo_postal String ( 15 ) (postal code) 2000-000
cidade String ( 50 ) (city) Porto
serie_id Integer (Associate a serie with a shop) 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 Shops / Warehouses

DELETE api/1.0/lojas/ID

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

Contacts (clients)

Valid requests:

In the Bill customers and suppliers are called contacts.

Get Contacts

GET api/1.0/contatos

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
page Integer (Page number...) 2
pesquisa[field] Make an exact search exacta for some value. Valid Fields: email, morada, codigo_postal, cidade, pais, site, telefone_contacto, observacoes, prazo_vencimento, retencao, activar_alerta, visivel johndoe@example.com
pesquisa[texto][field] Do a search like %valor%. Valid Fields: 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"
}]
}

Get Contact by ID

GET api/1.0/contatos/ID

Parameters
Field Type 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
}
}]
}

Create Contact (client)

POST api/1.0/contatos

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
nome 1 String (max:30) name (if you don't know you can call it (Consumidor Final) Julio Sousa
pais 1 Contry using format ISO 3166-1
alpha-2 (max:2) 		PT
código String (max:30 | Unique code) 28172272
nif String ( max:15 ) VAT Number 1
email email ( max:150 ) johndoe@example.com
morada String ( 100 ) Address Rua da saudade
codigo_postal String ( 15 ) Postal Code 2000-000
cidade String ( 50 ) City Porto
site String (255) http://www.example.com
pessoa_contato String (50) Contact Name Rua da saudade
telefone_contato String (30) Phone +351 21 282 23 23
observacoes String (250) Observation +351 21 282 23 23
prazo_vencimento Integer (Maturity date of the documents in days) 90
retencao Boolean (withholding) 1
activar_alerta Boolean (Create email alerts for
invoices due or past due)		 1
visivel Boolean (visible) 1
desconto_padrao (min:0, max:100) Default Discount Integer 5
alerta_dias_antes Integer (min:0, max:365) How many days before the invoice expires does it issue the notice 20
alerta_dias_depois Integer (min:0, max:365) How many days after the invoice expires, 14
metodo_pagamento_id Integer (Allows you to add the default payment method) 17
metodo_expedicao_id Integer (allows adding default shipping method) 28
lingua_padrao_documentos String (2) Can be: pt, fr, ou en (document language) pt
lojas Array (array with warehourses ids to which it belongs) ['2','12']
tipos Array (array with ids of the types it belongs to) ['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 Contact

PATCH api/1.0/contatos/ID

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
nome< String (max:30) name (if you don't know you can call it (Consumidor Final) Julio Sousa
pais Contry using format ISO 3166-1
alpha-2 (max:2) 		PT
código String (max:30 | Unique code) 28172272
nif String ( max:15 ) VAT Number 1
email email ( max:150 ) johndoe@example.com
morada String ( 100 ) Address Rua da saudade
codigo_postal String ( 15 ) Postal Code 2000-000
cidade String ( 50 ) City Porto
site String (255) http://www.example.com
pessoa_contato String (50) Contact Name Rua da saudade
telefone_contato String (30) Phone +351 21 282 23 23
observacoes String (250) Observation +351 21 282 23 23
prazo_vencimento Integer (Maturity date of the documents in days) 90
retencao Boolean (withholding) 1
activar_alerta Boolean (Create email alerts for
invoices due or past due)		 1
visivel Boolean (visible) 1
desconto_padrao (min:0, max:100) Default Discount Integer 5
alerta_dias_antes Integer (min:0, max:365) How many days before the invoice expires does it issue the notice 20
alerta_dias_depois Integer (min:0, max:365) How many days after the invoice expires, 14
metodo_pagamento_id Integer (Allows you to add the default payment method) 17
metodo_expedicao_id Integer (allows adding default shipping method) 28
lingua_padrao_documentos String (2) Can be: pt, fr, ou en (document language) pt
lojas Array (array with warehourses ids to which it belongs) ['2','12']
tipos Array (array with ids of the types it belongs to) ['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 Contact

DELETE api/1.0/contatos/ID

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

Products (Items)

Valid requests are:

Manage Your Products.

Get Products

GET api/1.0/items

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
page Integer (Pode enviar o número da página) 2
pesquisa[field] Search exacta by exact match of a field. Valid Fields: unidade_medida_id, ProductCategory, visivel, movimenta_stock, imposto_id, preco_custo, servico 1
pesquisa[texto][field] Search like %valor%. Valid Fiedls: 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": []
}]
}

Get Product By ID

GET api/1.0/items/ID

Parameters
Field Type 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": []
}

Create Product

POST api/1.0/items

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
descricao 1 String (max:200) Name Cadeira de Pinho
codigo 1 String (max:30) Unique Code (SKU) 2828211811-A
unidade_medida_id 1 Integer (ID of unit of measure) 12
imposto_id 1 Integer (tax id) 1
iva_compra 1 Integer (Tax id when you buy) 1
codigo_barras String (max:100) (barcode) 111291j181j1222sj22
ProductCategory String (1) Can Be:M,P,A,S,T 1
observacoes Text (observation) Verificar se ....
visivel Boolean (visible?) 1
movimenta_stock Boolean (move stock?) 1
servico Boolean (Is a service?) 0
preco_custo Numeric (cost price) 12.30
lojas Array (array com ids das lojas a que pertence) ['2','12']
categorias Array (array with store ids to which it belongs) ['12','32']
precos array (A set of prices, each price has 3 parameters) precos[0][preco_nome]=Preço 1 (price name)
precos[0][preco_sem_iva]=12.20 (price without tax)
precos[0][preco_com_iva]=15.20 (price with tax)
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 Product

PATCH api/1.0/items/ID

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer (deve ir no url) 12
descricao String (max:200) (name) Cadeira de Pinho
codigo String (max:30) (unique code SKU) 2828211811-A
unidade_medida_id Integer (Id unit of measure) 12
imposto_id Integer (id Tax) 1
iva_compra Integer (id Tax when you buy) 1
codigo_barras String (max:100) (barcode) 111291j181j1222sj22
ProductCategory String (1) Can be:M,P,A,S,T 1
observacoes Text (observation) Verificar se ....
visivel Boolean(is visible) 1
movimenta_stock Boolean (move stock) 1
servico Boolean (Is a service?) 0
preco_custo Numeric (cost price) 12.30
lojas Array (array com ids das lojas a que pertence) ['2','12']
categorias Array (array with store ids to which it belongs) ['12','32']
precos array (A set of prices, each price has 3 Parameters) precos[0][preco_nome]=Preço 1 (name)
precos[0][preco_sem_iva]=12.20 (price without taxes)
precos[0][preco_com_iva]=15.20 (price with taxes)
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 Product

DELETE api/1.0/items/ID

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

Documents

Valid Requests:

Get Documents

GET api/1.0/documentos

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
page Integer (Page Number) 2
pesquisa[field] Do a search using the exact value you provide. Valid Fields: tipo_documento_id, contato_id, terminado, metodo_pagamento_id, serie_id, loja_id, modulo_estado_id, estado johndoe@example.com
pesquisa[texto][field] Do a text search like %valor%. Valid Fiedls: viatura, invoice_number 500000000
pesquisa[order_by][field] You can order By the following Fields: 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"
}]
}

Open a Document By ID

GET api/1.0/documentos/ID

Parameters
Field Type 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}]}

Download a Document

note: O The PDF download path is external to our API. There is no need to send any token.

Note 2: At the insistence of the tax authority, the document will only be original in the first download. The second and subsequent downloads will have "duplicate" information. Therefore, to verify that the document is correct, it is advisable to use the option to open the document by its ID and not the option to download the document.

GET /documentos/download/ID_DO_DOCUMENTO/TOKEN_DOWNLOAD

Create Document

POST api/1.0/documentos

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 2 Integer - If you are editing a draft, you must send the document ID. Note that when a draft is edited, its ID changes, creating a new ID for this same document. 1
tipo_documento_id 2 Integer - Send the id of the Type of document 1
tipificacao 2 String (4) If you don't send the ID of the type of document you can use tipificação example FT for invoice):
FT, FR ....		 FT
contato_id 2 Integer - Not Mandatory. You can send a contact array and the contact will be created. If you send a code of the contact or a nif (vat number) that already exists in your account, that contact will be automatically selected. If you do not send either and only send the empty array, the document will be associated with the default Consumidor Final (the default anonymous customer). 15
contato 2 array (option if you send contato_id you don't need. Otherwise you can use it to create he client while you create the document.) Array
Field Type Example
nome String Max:150 (name) John Doe
email String Max:150 johndoe@example.com
nif String Max:15 (if is portuguese must be valid) 123456789
codigo String Max:30 (unique code) AB2718
morada String Max:100 (address) Rua de Algo n15 3b
codigo_postal String Max:15 (postal code) 2999-000
cidade String Max:50 (city) Aveiro
pais String Max:2 (country code) PT
site String Max:255 http://www.example.com
telefone_contacto String Max:50 (phone) 9138728232
produtos 1 Array (there may be several Arrays inside) Each one being a line of the document. Array
Field Type Example
item_id 2 Integer - Optional. If you don't send item_id (product id) and if you don't send codigo (product code) or a codigo tha don't exists,
the product will be created automaticly. 		30
codigo 2 String Max:30 (code) ABCEH212
nome 1 String Max:200 (product or service name) Cadeira XPTO - Azul #21
unidade_medida_id 2 Integer - You should only send this value if the item (product) does not exist in the database. Otherwise, it will be ignored. 2
ProductCategory 2 String (max:1) - Can be: M,P,A,S,T You should only send this value if the item (product) does not exist in the database. Otherwise, it will be ignored. 2
movimenta_stock 2 Boolean (move stock)You should only send this value if the item (product) does not exist in the database. Otherwise, it will be ignored.. 2
servico 2 Boolean (is a service?) You should only send this value if the item (product) does not exist in the database. Otherwise, it will be ignored. 2
quantidade 1 Float (min:0.00001) (Amount) 12
preco_unitario 1 Float (min:0) (price in euros for each unit). 12.00
imposto_id 2 Integer - optional. You can send imposto_id or imposto. if this product don't have taxes you should send imposto 0. 128
imposto 2 Integer - optional (Min:0 Max:100)
If you don't want to send the imposto_id. You can send the tax value. Example 23 (is 23%).
If the product don't have taxes send 0.		 23
isencao 2 String (Max:3) If you send imposto 0 or imposto_id 0 you must send the code of the Exemption reason. M01
desconto_1 Integer (min:0,Max:100) (discount number 1) 5
desconto_2 Integer (min:0,Max:100) (discount number 2) 6
desconto_3 Integer (min:0,Max:100) 15
retencao Integer (min:0,Max:100) You may have withholding tax. You must send the value. 11.5
lancamento_pai_id 2 Integer - Optional: You can refer to the line of another document. You must provide the ID of the line and not the id of the document. Example: You created a waybill, and now you are invoicing it. You can use lancamento_pai_id to refer that this line in this invoice was created from that line of that waybill.
Another example is in the creation of credit notes. It is mandatory by law to reference the original document or line on each line as a credit note is an amending document. If you want to issue a credit note for a document created by other software, you can use the referencia_manual field. 		13822
referencia_manual 2 String - SIf for some reason you want to issue a credit note for an external document, or if you simply want to reference a source document on an invoice. Whenever you need to make a reference and if possible try to use lancamento_pai_id
to refer to the original release.		 FT A282/182822
loja_id Integer - If not sent, the store associated with the user will be used. If none exists, the default shop will be used. 18
serie_id Integer - If not sent, the default series of the chosen shop will be used. 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 -If not sent, the payment method associated with the default contact (client) will be used. If it does not exist, the company's default payment method will be used. 23
data Data no Formato: Y-m-d H:i:s if not sent, the date and time of mainland Portugal at the time will be used. 2017-08-12 10:32:23
prazo_vencimento Data no Formato: Y-m-d H:i:s if not sent, the date and time will be used, adding up the associated expiration days or client (contact). 2017-08-12 10:32:23
morada String Max:100 Optional:if you want to bill with different data than the customer's headquarters. Rua de Algo n15 3b
codigo_postal String Max:15 Optional: if you want to bill with different data than the customer's headquarters. 2999-000
cidade String Max:50 Optional: if you want to bill with different data than the customer's headquarters. Aveiro
pais String Max:2 Optional: if you want to bill with different data than the customer's headquarters. PT
carga_morada String Max:100 Optional: Only mandatory in transport documents Rua de Algo n15 3b
carga_codigo_postal String Max:15 Optional: Only mandatory in transport documents 2999-000
carga_cidade String Max:50 Opcional: Only mandatory in transport documents Aveiro
carga_pais String Max:2 Opcional: Only mandatory in transport documents PT
data_carga Data no Formato: Y-m-d H:i:s (when creating transport documents the date of loading and unloading are mandatory) 2017-08-12 10:32:23
descarga_morada String Max:100 Optional: Apenas obrigatorio em documentos de transporte Rua de Algo n15 3b
descarga_codigo_postal String Max:15 Optional: Apenas obrigatorio em documentos de transporte 2999-000
descarga_cidade String Max:50 Optional: Apenas obrigatorio em documentos de transporte Aveiro
descarga_pais String Max:2 Optional: Apenas obrigatorio em documentos de transporte PT
data_descarga Data no Formato: Y-m-d H:i:s (when creating transport documents the date of loading and unloading are mandatory) 2017-08-12 10:32:23
viatura String max:20 - (Transport documents must have the vehicle registration number to be valid) XX-28-12
moeda String (max:3) Formato:ISO 4217 http://www.xe.com/iso4217.php. All documents are created in EURO, however you can refer to the foreign currency value at the end of the document. USD
cambio 2 Float - Exchange value against the EURO. Only mandatory if the document refers to foreign currency. 1.21
observacoes String (max:200) - Appears at the end of the document. O cliente deseja que seja entregue a fatura no piso 1.
nota_documento String (Text) - internal note not visible in the document. Lorem ipsum dolor sit amet, consectetur adipisicing elit. Debitis illo aspernatur, iure, veritatis minus molestiae!
modulo_estado_id Integer - (state id) You can assign a status to this document. 2
lingua String (max:2) - The bill allows invoices to be issued in 3 languages. Portuguese, French and English. One of the following values ​​is then accepted: pt, fr, en fr
arredondamento Float: min:-0.03|max:0.03 - By law it is possible to apply a manual rounding to the total of a document. This positive or negative rounding is a maximum value of 3 cents. -0.01
terminado boolean - If you want to finish the document, send true or 1. Otherwise, the document will be saved as a draft./td> 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
  }
}]
}

Cancel Document

PATCH api/1.0/documentos

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer - Document ID 12
motivo_anular 1 String (max:200) by law you are required to specify the reason why you will cancel the document Um erro no preço do produto.
data Data no Formato: Y-m-d H:i:s if not sent, the date and time of mainland Portugal at the time will be used. 2017-08-12 10:32:23
Response 
  {"id":3410,"estado":"A"}

Delete Document

It is only possible in drafts.

DELETE api/1.0/documentos/ID

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

Open Balance Document

It allows to register a debt to supplier or a debt that the customer owes us. This document cannot be printed, used only to control debts prior to the system.

POST api/1.0/documentos/saldo-inicial

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
contato_id 1 Integer - contact id 12
serie_id Integer - If not sent, the default series of the chosen store will be used. 12
observacoes String (max:200) observations Divida referente ao periodo de X a Y.
data Data no Formato: Y-m-d H:i:s and not sent, the date and time of mainland Portugal at the time will be used. 2017-08-12 10:32:23
prazo_vencimento Data no Formato: Y-m-d H:i:s and not sent, the date and time of mainland Portugal at the time will be used. 2017-08-12 10:32:23
prazo_vencimento Data no Formato: Y-m-d H:i:s and not sent, the date and time of mainland Portugal at the time will be used. 2017-08-12 10:32:23
tipo_documento_id Integer - Only values ​​are accepted: 26 or 27 And they are: 26 - Customer Balance 27 - Supplier Balance, respectively. 26
metodo_pagamento_id Integer - If not sent, the payment method associated with the default customer will be used. 32
net_total 1 Float - Open Balance Without TAXES 12.28
gross_total 1 Float - Open Balance With Taxes 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}}

Comunicate Transportation Document

For the guide to be communicated, you must have the tax authority's user data correctly configured in the company's settings. The tax authority webservices are not functional 100% of the time. In some cases you may have to try communication again. If it is not possible, you can communicate using the Tax Authority website and place the code assigned to the guide manually.

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

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer - ID of the document 12
Response 
  {"resultado":"...","codigo_at":"328282772"}

Add Tax Authority Code Manually

The tax authority's web services are not functional 100% of the time. If it is not possible to do so, you can communicate using the AT website and place the code assigned to the guide manually.

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

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer - Document ID 12
codigo_at 1 The code 28283723
Response 
  {"id":3442,"invoice_number":"FT B2016\/1","codigo_at":"2181821"}

Send Document By E-mail

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

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

Add Note To Document

POST api/1.0/documentos/nota-documento

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer - Document ID 12
nota_documento 1 nota_documento (information) 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

Valid Requests:

Check Stock

GET api/1.0/stock

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
data_stock Data no Formato: Y-m-d H:i:s if not sent, the date and time of mainland Portugal will be used at the time. 2017-08-12 10:32:23
lojas Array with IDs if you want to filter by stores. [1,32]
itens Array with ID's if you want to filter by products [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}}]}

See Stock of a Product In specific Warehouse

This request is ideal to quickly access the stock available for a specific product in a specific store. But it is possible to get the same information with the previous request.

GET api/1.0/stock/singular

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
data_stock Data no Formato: Y-m-d H:i:s if not sent, the date and time of mainland Portugal will be used at the moment. 2017-08-12 10:32:23
item_id 1 Integer Product ID 222
loja_id 1 Integer Warehouse ID 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
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
data_stock Data no Formato: Y-m-d H:i:s if not sent, the date and time of mainland Portugal will be used at the moment. 2017-08-12 10:32:23
lojas Array with IDs if you want to filter by warehouses [1,32]
itens Array with ID's if you want to filter by products [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"}]}

Movements

Valid Requests

Pending conversion movements for a contact (client)

With this request you will be able to see documents that are pending movements for a single contact (client). You can send the tipificacao (eg:FT) of the document you want to create and then see only the documents that can be converted by that tipificacao. Example: If you want to import entries for an invoice that you are going to create you can send FT. You will then see all pending movements for budgets, guides, etc. If you want to create a credit note, you can send NC and see all documents that can be converted into a credit note. Then you can use one of the following requests to view the entries for each of the documents.

GET api/1.0/movimentos-pendentes

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
contato_id 1 Integer - To convert a document, remember that it must be from the same customer. Example a bill of lading 13
tipificacao String (max:3) - If you want to create an Invoice, send the FT type and you will see which pending documents can be converted by invoice. 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"}}]}

See Pending Movements of Multiple Documents

GET api/1.0/movimentos-pendentes/multiplos

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Array with IDs of the documents you want to see pending entries [1,32]
Response

Returns an array. Each key being the ID of one of the searched documents. For a smooth time inside this element there is once again an array with pending entries.

  {"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"}}}}]}

View pending movements of a document by ID

GET api/1.0/movimentos-pendentes/ID

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
id 1 Integer - Document ID 53
Response

Returns an array of peding movements for the respective document. 

  [{"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"}}}}]

Receipts

Valid Requests:

Create Receipt

POST api/1.0/recibos

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
contato_id 1 Integer (contact id) 12
tipo_documento_id 1 Integer (Can be 28 - Normal Receipt, or supplier receipt 29) 12
documentos 1 Array with info of documents to be paid Array
Field Type Example
documentos[0][documento_id] 1 Integer - Document ID we are paying for. One array line for each document that will be paid on this receipt 30
documentos[0][total] 1 Float (Paymente amount) this amount must not contain the discount amount. The total deducted in the document will be:
total + total_desconto = total_paid
Example: a document of 50.00 € can be paid in full as follows:
total = 30.00, total_desconto = 20.00 (discount) 		30.00
documentos[0][total_desconto] 1 Float (total value of a discount) 12.20
data Data no Formato: Y-m-d H:i:s if not sent, the date and time of mainland Portugal will be used at the moment. 2017-08-12 10:32:23
serie_id Integer - If not sent, the default series of the chosen warehouse will be used. 12
metodo_pagamento_id Integer - If not sent, the payment method associated with the default client will be used. 32
lingua (String max:2) (language) Can be pt,en,fr pt
morada (String max:100) Address Rua da Saudade n25
codigo_postal (String max:15) Postal Code 1000-000
cidade (String max:50) City Porto
pais (String max:2) Country Code PT
observacoes (String max:200) (observations) 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":""}}

Generate Receipt for a Document by its ID

POST api/1.0/recibos/pagar/ID_DOCUMENTO

Parameters
Field Type 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":""}}

Tax Authority

Valid Requests:

These requests are related to the communication of saf-t files or guides to the tax authority. They allow the configuration of the AT website data as well as the testing of them.

Configure Tax Authority Username and Password

It allows configuring the password and user of the tax authority webservice

POST api/1.0/at/configurar

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

Login Test

Allows you to test the credentials to see if it is ok.

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

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

Current State

It allows to test the data if the defined data has already been tested or not and if they are correct. Whenever the data is updated and the login is not tested again this value will return to false.

POST api/1.0/at/estado-configuracao

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

Comunications Log

Each Transport Guide communication or SAF-T file is registered. You can check the log.

POST api/1.0/at/registo-comunicacoes

Parameters
Field Type Example
api_token 1 String (128) 4zA1HOjFTqXzv5kpCfEA58WG2.......dM
pesquisa[field] You can do an exact search. Valid Fields: tipo, sucesso pesquisa[tipo]=saft
pesquisa[texto][field] Do a text search like %valor% pValid Fiedls: 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"
        }
    ]
}